@xelth/eck-snapshot 2.1.0 → 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dmytro Surovtsev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,117 +1,126 @@
 # 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).
+A powerful CLI tool to create and restore single-file text snapshots of Git repositories and directories. Generate comprehensive snapshots containing directory structure and file contents, optimized for providing context to Large Language Models (LLMs) like Claude, Gemini, and ChatGPT.
+
+## ✨ What's New in v3.0.0
+
+🎯 **Universal Directory Support**: Works with any directory, not just Git repositories  
+🤖 **Enhanced AI Instructions**: Improved headers with detailed guidance for AI assistants  
+⚡ **Auto-Detection**: Automatically switches to directory mode when Git isn't available  
+🧹 **Clean Mode**: Option to create snapshots without AI instructions  
 
 ## 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 complete project context is crucial for accurate results. Manually copying and pasting dozens of files is tedious and error-prone.
 
-## Key Features
+eck-snapshot automates this by generating a single, comprehensive text file of your entire project. This is particularly effective with models that support large context windows (like Gemini 2.0 Pro with 1M tokens), allowing the entire project to be analyzed at once.
 
-  * **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.
-  * **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.
-  * **Compression**: Supports gzipped (`.gz`) snapshots for smaller file sizes.
+## 🚀 Key Features
 
-## Demo
+### 📁 **Universal Compatibility**
+- **Git Repositories**: Leverages `git ls-files` and respects `.gitignore`
+- **Any Directory**: Recursively scans any folder structure
+- **Auto-Detection**: Automatically switches modes based on Git availability
 
-Here's an example of `eck-snapshot` in action:
+### 🤖 **AI-Optimized**
+- **Structured Headers**: Detailed instructions for AI assistants
+- **Clean Mode**: Option to skip AI headers for general use
+- **LLM-Ready Format**: Optimized for Claude, Gemini, ChatGPT, and other models
 
-```
-🚀 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
-...
-==================================================
-```
+### ⚡ **Advanced Features**
+- **Multiple Formats**: Plain text (Markdown) and JSON output
+- **Compression**: Built-in gzip support for smaller files
+- **Smart Filtering**: Configurable ignore patterns and size limits
+- **Restore Capability**: Recreate entire project structures from snapshots
+- **Progress Tracking**: Real-time progress bars and detailed statistics
+
+### 🔒 **Security & Performance**
+- **Path Validation**: Prevents directory traversal attacks
+- **Parallel Processing**: Concurrent file handling for speed
+- **Memory Efficient**: Handles large projects without memory issues
 
-The beginning of the generated file will look like this:
+## 📦 Installation
+
+```bash
+npm install -g @xelth/eck-snapshot
+```
 
-```text
-Directory Structure:
+## 🎯 Quick Start
 
-├── .github/
-│   └── workflows/
-│       └── publish.yml
-├── src/
-│   ├── utils/
-│   │   └── formatters.js
-│   └── index.js
-├── .gitignore
-├── package.json
-└── README.md
+### Create Snapshots
 
+```bash
+# Git repository (default mode)
+eck-snapshot
 
---- File: /src/index.js ---
+# Any directory (auto-detects non-git folders)
+eck-snapshot /path/to/any/folder
 
-#!/usr/bin/env node
-import { Command } from 'commander';
-// ... rest of the file content
+# Force directory mode (ignores git)
+eck-snapshot --dir .
 
---- File: /package.json ---
+# Clean snapshot without AI instructions
+eck-snapshot --no-ai-header
 
-{
-  "name": "eck-snapshot",
-  "version": "2.1.0",
-  // ... rest of the file content
+# Compressed JSON format
+eck-snapshot --format json --compress
 ```
 
-## Installation
-
-To install the tool globally, run the following command:
+### Restore from Snapshots
 
 ```bash
-npm install -g @xelth/eck-snapshot
-```
+# Basic restore
+eck-snapshot restore snapshot.md
 
-## Usage
+# Restore to specific directory
+eck-snapshot restore snapshot.md ./restored-project
 
-Once installed, you can run the tool from any directory in your terminal.
+# Preview without writing files
+eck-snapshot restore snapshot.md --dry-run
 
-### Creating a Snapshot
+# Restore only specific files
+eck-snapshot restore snapshot.md --include "*.js" "*.json"
+```
 
-```bash
-# Create a snapshot of the current directory
-eck-snapshot
+## 📋 Usage Examples
+
+### For AI Development
 
-# Specify a path to another repository
-eck-snapshot /path/to/your/other/project
+```bash
+# Create AI-optimized snapshot for Gemini/Claude
+eck-snapshot --format md --compress
+# Result: project_snapshot_2025-01-19_12-00-00.md.gz
 
-# Save the snapshot to a different directory and exclude the tree view
-eck-snapshot --output ./backups --no-tree
+# Clean snapshot for general documentation
+eck-snapshot --no-ai-header --output ./docs
 ```
 
-### Restoring from a Snapshot
+### Project Backup & Migration
 
 ```bash
-# Restore files from a snapshot into the current directory
-eck-snapshot restore ./snapshots/project_snapshot_...txt
+# Full project backup
+eck-snapshot --include-hidden --format json --compress
 
-# Restore into a new directory without a confirmation prompt
-eck-snapshot restore snapshot.txt ./restored-project --force
+# Selective restore
+eck-snapshot restore backup.json.gz --exclude "node_modules/*" --include "src/*"
 ```
 
-## Configuration
+### Cross-Platform Development
+
+```bash
+# Create snapshot on Windows
+eck-snapshot --output ./transfer
+
+# Restore on Linux/Mac
+eck-snapshot restore transfer/project_snapshot.md ./project
+```
 
-You can create a `.ecksnapshot.config.js` file in your project's root directory to customize the tool's behavior.
+## ⚙️ Configuration
 
-**Example `.ecksnapshot.config.js`:**
+Create `.ecksnapshot.config.js` in your project root:
 
 ```javascript
 export default {
@@ -119,23 +128,165 @@ export default {
   filesToIgnore: [
     'package-lock.json',
     '*.log',
+    '*.tmp'
   ],
+  
   // File extensions to ignore
   extensionsToIgnore: [
     '.sqlite3',
     '.env',
+    '.DS_Store',
+    '.ico',
+    '.png',
+    '.jpg'
   ],
-  // Directories to ignore (must have a trailing slash)
+  
+  // Directories to ignore
   dirsToIgnore: [
     'node_modules/',
     '.git/',
     'dist/',
+    'build/',
+    'coverage/'
   ],
-  // Maximum size for individual files
+  
+  // Size and performance limits
   maxFileSize: '10MB',
+  maxTotalSize: '100MB',
+  maxDepth: 10,
+  concurrency: 10
 };
 ```
 
-## License
+## 📖 Command Reference
+
+### Snapshot Command
+
+```bash
+eck-snapshot [options] [path]
+```
+
+**Core Options:**
+- `-o, --output <dir>` - Output directory (default: ./snapshots)
+- `-d, --dir` - Directory mode: scan any folder recursively
+- `--no-ai-header` - Skip AI instruction header (clean mode)
+- `-v, --verbose` - Show detailed processing information
+
+**Format & Compression:**
+- `--format <type>` - Output format: md (default) or json
+- `--compress` - Create gzipped output (.gz extension)
+- `--no-tree` - Exclude directory tree from output
+
+**Filtering:**
+- `--include-hidden` - Include hidden files (starting with .)
+- `--max-file-size <size>` - Maximum individual file size (e.g., 5MB)
+- `--max-total-size <size>` - Maximum total snapshot size (e.g., 50MB)
+- `--config <path>` - Path to custom configuration file
+
+### Restore Command
+
+```bash
+eck-snapshot restore [options] <snapshot_file> [target_directory]
+```
+
+**Control Options:**
+- `-f, --force` - Skip confirmation prompts
+- `--dry-run` - Preview without writing files
+- `-v, --verbose` - Show detailed processing information
+
+**Filtering:**
+- `--include <patterns>` - Include only matching files (wildcards supported)
+- `--exclude <patterns>` - Exclude matching files (wildcards supported)
+- `--concurrency <number>` - Number of concurrent operations (default: 10)
+
+## 🎭 Working with AI Models
+
+### For Gemini 2.0 Pro (1M context)
+```bash
+# Create comprehensive snapshot with AI instructions
+eck-snapshot --format md --compress
+```
+The generated file includes detailed instructions for Gemini to analyze your project and provide structured commands for Claude Code.
+
+### For Claude Code
+```bash
+# Clean, focused snapshot
+eck-snapshot --no-ai-header --max-total-size 200MB
+```
+
+### For ChatGPT/Other Models
+```bash
+# Standard snapshot with moderate size limits
+eck-snapshot --max-total-size 50MB --no-ai-header
+```
+
+## 🔧 Advanced Use Cases
+
+### Monorepo Support
+```bash
+# Snapshot specific package in monorepo
+eck-snapshot ./packages/core --dir --output ./snapshots/core
+
+# Multiple packages
+eck-snapshot ./packages/api --dir && eck-snapshot ./packages/web --dir
+```
+
+### CI/CD Integration
+```bash
+# Create release snapshot
+eck-snapshot --format json --compress --output ./artifacts
+
+# Documentation generation
+eck-snapshot --no-ai-header --format md --output ./docs/snapshots
+```
+
+### Migration & Archival
+```bash
+# Complete project archive
+eck-snapshot --include-hidden --format json --compress --max-total-size 1GB
+
+# Selective migration
+eck-snapshot restore archive.json.gz --include "src/*" "docs/*" --exclude "*.test.*"
+```
+
+## 📊 Output Formats
+
+### Markdown Format (Default)
+- Human-readable structure
+- AI instruction headers (optional)
+- Directory tree visualization
+- File content with clear delimiters
+
+### JSON Format
+- Structured metadata
+- Programmatic processing friendly
+- Includes statistics and file information
+- Perfect for automation workflows
+
+## 🛡️ Security Features
+
+- **Path Validation**: Prevents directory traversal during restore
+- **File Sanitization**: Validates all file paths and names
+- **Confirmation Prompts**: Requires approval before overwriting files
+- **Size Limits**: Protects against extremely large operations
+
+## 🚀 Performance
+
+- **Parallel Processing**: Concurrent file operations for speed
+- **Progress Tracking**: Real-time progress bars for long operations
+- **Memory Efficient**: Streams large files to avoid memory issues
+- **Smart Caching**: Optimized for repeated operations
+
+## 📝 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 📞 Support
 
-This project is licensed under the MIT License.
+- **Issues**: [GitHub Issues](https://github.com/xelth-com/eckSnapshot/issues)
+- **Documentation**: This README and `--help` commands
+- **Examples**: See the examples directory in the repository

package/index.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 
+
+
 import { Command } from 'commander';
 import { execa } from 'execa';
 import fs from 'fs/promises';
@@ -28,8 +30,157 @@ const DEFAULT_CONFIG = {
   concurrency: 10
 };
 
-// ... (остальные существующие функции: parseSize, formatSize, matchesPattern, loadConfig, и т.д. остаются без изменений)
-// --- НАЧАЛО СУЩЕСТВУЮЩИХ ФУНКЦИЙ ---
+
+
+/**
+ * Generates the detailed, universal Markdown header for the snapshot file.
+ * This header contains the full operational instructions for the AI model.
+ * @param {object} stats - The statistics object from the snapshot process.
+ * @param {string} repoName - The name of the repository.
+ * @returns {string} A formatted Markdown string with comprehensive AI instructions.
+ */
+function generateSnapshotHeader(stats, repoName, includeAiInstructions = true) {
+  const timestamp = new Date().toISOString();
+  
+  if (!includeAiInstructions) {
+    return `# Repository Snapshot
+
+**Repository:** ${repoName}  
+**Generated:** ${timestamp}  
+**Tool:** eck-snapshot  
+**Files Included:** ${stats.includedFiles} of ${stats.totalFiles}
+
+---
+
+`;
+  }
+  
+  return `# AI Instructions
+
+## 1. How to Read This Snapshot
+
+This document is a self-contained, single-file snapshot of the **${repoName}** software repository, generated by the \`eck-snapshot\` tool on **${timestamp}**. It is designed to provide a Large Language Model (LLM) with the complete context of a project.
+
+* **Source of Truth:** Treat this snapshot as the complete and authoritative source code.
+* **Structure:** The file contains a **Directory Structure** tree, followed by the full content of each file, demarcated by \`--- File: /path/to/file ---\` headers.
+
+**Snapshot Stats:**
+- **Files Included:** ${stats.includedFiles}
+- **Total Files in Repo:** ${stats.totalFiles}
+
+---
+
+## 2. Your Core Operational Workflow
+
+You are the Project Manager and Solution Architect AI. Your primary goal is to translate user requests into technical plans and then generate precise commands for a code-execution AI agent.
+
+### PROJECT OVERVIEW
+- **Project:** ${repoName}
+- **Description:** A CLI tool to create and restore single-file text snapshots of a Git repository, optimized for providing context to Large Language Models (LLMs).
+
+### CORE WORKFLOW: The Interactive Command Cycle
+1.  **Analyze User Request:** Understand the user's goal in their native language.
+2.  **Formulate a Plan:** Create a high-level technical plan to solve the user's request.
+3.  **Propose & Await Confirmation:** Present the plan to the user in their language and ask for approval to generate the command. **CRITICAL: Stop and wait for the user's response. Do NOT generate the command block at this stage.**
+4.  **Generate Command on Demand:** This is the execution step, triggered ONLY by a positive user response.
+    -   **On Approval:** If the user confirms the plan (e.g., "yes", "proceed") or provides a minor correction, your *next response* must be **only the command block**. Do not include any conversational text.
+    -   **On Direct Order:** If the user explicitly asks for the command (e.g., "make the command for Claude now") and you have all the necessary information, you may skip step 3 and directly generate the command block.
+5.  **Review & Report:** After the command is executed, analyze the results and report back to the user in their language.
+6.  **Iterate:** Continue the cycle based on user feedback.
+
+### COMMUNICATION PROTOCOL
+-   **User Interaction:** ALWAYS communicate with the user in the language they use.
+-   **Agent Commands:** ALWAYS formulate the JSON payload and technical instructions for the execution agent in **ENGLISH** to ensure technical accuracy.
+
+### COMMAND BLOCK FORMAT
+To ensure error-free execution, all tasks for the agent must be presented in a special block with a "Copy" button. Use this enhanced format for maximum clarity and execution accuracy:
+
+\`\`\`json
+{
+  "command_for_agent": "apply_code_changes",
+  "task_id": "unique-task-id",
+  "payload": {
+    "objective": "Brief, clear task description",
+    "context": "Why this change is needed",
+    "files_to_modify": [
+      {
+        "path": "exact/file/path.js",
+        "action": "specific action (add, modify, replace, delete)",
+        "location": "line numbers, function name, or search pattern",
+        "details": "precise description of the change"
+      }
+    ],
+    "new_files": [
+      {
+        "path": "path/to/new/file.js",
+        "content_type": "javascript/json/markdown/config",
+        "purpose": "why this file is needed"
+      }
+    ],
+    "dependencies": {
+      "install": ["package-name@version"],
+      "remove": ["old-package-name"]
+    },
+    "validation_steps": [
+      "npm run test",
+      "node index.js --help",
+      "specific command to verify functionality"
+    ],
+    "expected_outcome": "what should work after changes"
+  }
+}
+\`\`\`
+
+### PROJECT CONTEXT (\`eck-snapshot\`)
+-   **Type:** Node.js CLI Application, executed directly.
+-   **Module System:** ES Modules (\`"type": "module"\` in package.json).
+-   **Main File:** \`index.js\` contains all primary logic (837 lines).
+-   **Configuration:** \`.ecksnapshot.config.js\` is used for custom filtering and settings.
+-   **Key Dependencies:** \`commander\`, \`execa\`, \`inquirer\`, \`ignore\`, \`p-limit\`, \`cli-progress\`.
+
+### ARCHITECTURE DETAILS FOR CLAUDE CODE
+**Core Functions Location:**
+- \`createRepoSnapshot()\` - Line 333: Main snapshot creation
+- \`restoreSnapshot()\` - Line 579: Snapshot restoration  
+- \`processFile()\` - Line 265: Individual file processing
+- \`generateDirectoryTree()\` - Line 224: Tree generation
+- \`generateSnapshotHeader()\` - Line 42: AI instruction header
+- CLI setup - Lines 800-837: Commander.js configuration
+
+**Common Modification Patterns:**
+- CLI options: Modify commander setup (lines 808-822, 824-835)
+- Configuration: Update DEFAULT_CONFIG object (lines 23-31)
+- File processing: Enhance processFile() function
+- Output formats: Modify generateSnapshotHeader() or output logic
+- Dependencies: Update package.json and import statements
+
+**Testing Status:**
+- No test framework currently configured
+- package.json test script returns error
+- Manual testing via \`node index.js\` commands
+- Consider adding vitest or jest for future testing
+
+**Development Workflow:**
+- Direct execution: \`node index.js [command] [options]\`
+- Package creation: \`npm pack\`
+- Local testing: \`node index.js --help\`
+- Configuration testing: modify \`.ecksnapshot.config.js\`
+
+**Critical Implementation Notes:**
+- All file paths normalized to forward slashes
+- ES module imports only (no CommonJS)
+- Error handling with detailed user messages
+- Progress tracking for long operations
+- Security: Path validation prevents directory traversal
+- Cross-platform compatibility maintained
+
+---
+`;
+}
+
+
+
+
 
 function parseSize(sizeStr) {
   const units = { B: 1, KB: 1024, MB: 1024 ** 2, GB: 1024 ** 3 };
@@ -67,7 +218,6 @@ function matchesPattern(filePath, patterns) {
 
 async function loadConfig(configPath) {
   let config = { ...DEFAULT_CONFIG };
-  
   if (configPath) {
     try {
       const configModule = await import(path.resolve(configPath));
@@ -82,7 +232,6 @@ async function loadConfig(configPath) {
       '.ecksnapshot.config.mjs',
       'ecksnapshot.config.js'
     ];
-    
     for (const configFile of possibleConfigs) {
       try {
         await fs.access(configFile);
@@ -110,11 +259,55 @@ async function checkGitAvailability() {
 async function checkGitRepository(repoPath) {
   try {
     await execa('git', ['rev-parse', '--git-dir'], { cwd: repoPath });
+    return true;
   } catch (error) {
-    throw new Error(`Not a git repository: ${repoPath}`);
+    return false;
   }
 }
 
+async function scanDirectoryRecursively(dirPath, config, relativeTo = dirPath) {
+  const files = [];
+  
+  try {
+    const entries = await fs.readdir(dirPath, { withFileTypes: true });
+    
+    for (const entry of entries) {
+      const fullPath = path.join(dirPath, entry.name);
+      const relativePath = path.relative(relativeTo, fullPath).replace(/\\/g, '/');
+      
+      // Skip if matches ignore patterns
+      if (config.dirsToIgnore.some(dir => 
+        entry.name === dir.replace('/', '') || 
+        relativePath.startsWith(dir)
+      )) {
+        continue;
+      }
+      
+      // Skip hidden files unless explicitly included
+      if (!config.includeHidden && entry.name.startsWith('.')) {
+        continue;
+      }
+      
+      if (entry.isDirectory()) {
+        const subFiles = await scanDirectoryRecursively(fullPath, config, relativeTo);
+        files.push(...subFiles);
+      } else {
+        // Skip ignored files and extensions
+        if (config.extensionsToIgnore.includes(path.extname(entry.name)) ||
+            matchesPattern(relativePath, config.filesToIgnore)) {
+          continue;
+        }
+        
+        files.push(relativePath);
+      }
+    }
+  } catch (error) {
+    console.warn(`⚠️  Warning: Could not read directory: ${dirPath} - ${error.message}`);
+  }
+  
+  return files;
+}
+
 async function loadGitignore(repoPath) {
   try {
     const gitignoreContent = await fs.readFile(path.join(repoPath, '.gitignore'), 'utf-8');
@@ -142,7 +335,6 @@ async function readFileWithSizeCheck(filePath, maxFileSize) {
 
 async function generateDirectoryTree(dir, prefix = '', allFiles, depth = 0, maxDepth = 10, config) {
   if (depth > maxDepth) return '';
-  
   try {
     const entries = await fs.readdir(dir, { withFileTypes: true });
     const sortedEntries = entries.sort((a, b) => {
@@ -150,16 +342,13 @@ async function generateDirectoryTree(dir, prefix = '', allFiles, depth = 0, maxD
       if (!a.isDirectory() && b.isDirectory()) return 1;
       return a.name.localeCompare(b.name);
     });
-    
     let tree = '';
     const validEntries = [];
     
     for (const entry of sortedEntries) {
       if (config.dirsToIgnore.some(d => entry.name.includes(d.replace('/', '')))) continue;
-      
       const fullPath = path.join(dir, entry.name);
       const relativePath = path.relative(process.cwd(), fullPath).replace(/\\/g, '/');
-      
       if (entry.isDirectory() || allFiles.includes(relativePath)) {
         validEntries.push({ entry, fullPath, relativePath });
       }
@@ -171,7 +360,6 @@ async function generateDirectoryTree(dir, prefix = '', allFiles, depth = 0, maxD
       
       const connector = isLast ? '└── ' : '├── ';
       const nextPrefix = prefix + (isLast ? '    ' : '│   ');
-
       if (entry.isDirectory()) {
         tree += `${prefix}${connector}${entry.name}/\n`;
         tree += await generateDirectoryTree(fullPath, nextPrefix, allFiles, depth + 1, maxDepth, config);
@@ -227,10 +415,10 @@ async function processFile(filePath, config, gitignore, stats) {
     
     stats.includedFiles++;
     stats.includedFileTypes.set(fileExt, (stats.includedFileTypes.get(fileExt) || 0) + 1);
-    
     return { content: fileContent, size: fileContent.length };
   } catch (error) {
-    const errorReason = error.message.includes('too large') ? 'file-too-large' : 'read-error';
+    const errorReason = error.message.includes('too large') ?
+      'file-too-large' : 'read-error';
     
     stats.errors.push({ file: filePath, error: error.message });
     stats.skippedFiles++;
@@ -255,12 +443,11 @@ async function processFile(filePath, config, gitignore, stats) {
 // --- ОСНОВНЫЕ ФУНКЦИИ ДЛЯ КОМАНД ---
 
 async function createRepoSnapshot(repoPath, options) {
-  // ... (эта функция остается без изменений)
   const absoluteRepoPath = path.resolve(repoPath);
   const absoluteOutputPath = path.resolve(options.output);
   const originalCwd = process.cwd();
 
-  console.log(`🚀 Starting snapshot for repository: ${absoluteRepoPath}`);
+  console.log(`🚀 Starting snapshot for ${options.dir ? 'directory' : 'repository'}: ${absoluteRepoPath}`);
   console.log(`📁 Snapshots will be saved to: ${absoluteOutputPath}`);
 
   try {
@@ -269,19 +456,37 @@ async function createRepoSnapshot(repoPath, options) {
     config.maxTotalSize = options.maxTotalSize || config.maxTotalSize;
     config.maxDepth = options.maxDepth || config.maxDepth;
     config.includeHidden = options.includeHidden || false;
-
-    await checkGitAvailability();
-    await checkGitRepository(absoluteRepoPath);
+    
+    let allFiles = [];
+    let gitignore = null;
+    let isGitRepo = false;
+    
+    // Check if it's a git repository (unless --dir is explicitly used)
+    if (!options.dir) {
+      await checkGitAvailability();
+      isGitRepo = await checkGitRepository(absoluteRepoPath);
+      
+      if (!isGitRepo) {
+        console.log('ℹ️  Not a git repository, switching to directory mode');
+        options.dir = true;
+      }
+    }
     
     process.chdir(absoluteRepoPath);
     console.log('✅ Successfully changed working directory');
 
-    const gitignore = await loadGitignore(absoluteRepoPath);
-
-    console.log('📋 Fetching file list from Git...');
-    const { stdout } = await execa('git', ['ls-files']);
-    const allFiles = stdout.split('\n').filter(Boolean);
-    console.log(`📊 Found ${allFiles.length} total files in the repository`);
+    if (options.dir) {
+      console.log('📋 Scanning directory recursively...');
+      allFiles = await scanDirectoryRecursively(absoluteRepoPath, config);
+      gitignore = ignore(); // Empty gitignore for directory mode
+      console.log(`📊 Found ${allFiles.length} total files in the directory`);
+    } else {
+      gitignore = await loadGitignore(absoluteRepoPath);
+      console.log('📋 Fetching file list from Git...');
+      const { stdout } = await execa('git', ['ls-files']);
+      allFiles = stdout.split('\n').filter(Boolean);
+      console.log(`📊 Found ${allFiles.length} total files in the repository`);
+    }
 
     const stats = {
       totalFiles: allFiles.length,
@@ -295,7 +500,6 @@ async function createRepoSnapshot(repoPath, options) {
       skipReasons: new Map(),
       skippedFilesDetails: new Map()
     };
-
     let snapshotContent = '';
 
     if (options.tree) {
@@ -308,13 +512,13 @@ async function createRepoSnapshot(repoPath, options) {
 
     console.log('📝 Processing files...');
     const limit = pLimit(config.concurrency);
-    const progressBar = options.verbose ? null : new SingleBar({
+    const progressBar = options.verbose ?
+      null : new SingleBar({
       format: 'Progress |{bar}| {percentage}% | {value}/{total} files | ETA: {eta}s',
       barCompleteChar: '\u2588',
       barIncompleteChar: '\u2591',
       hideCursor: true
     }, Presets.shades_classic);
-
     if (progressBar) progressBar.start(allFiles.length, 0);
 
     const filePromises = allFiles.map((filePath, index) => 
@@ -325,6 +529,7 @@ async function createRepoSnapshot(repoPath, options) {
           progressBar.update(index + 1);
         } else if (options.verbose) {
           if (result.skipped) {
+            
             console.log(`⏭️  Skipping: ${filePath} (${result.reason})`);
           } else {
             console.log(`✅ Processed: ${filePath}`);
@@ -334,14 +539,12 @@ async function createRepoSnapshot(repoPath, options) {
         return result;
       })
     );
-
     const results = await Promise.allSettled(filePromises);
     if (progressBar) progressBar.stop();
 
     const contentArray = [];
     let totalSize = 0;
     const maxTotalSize = parseSize(config.maxTotalSize);
-
     for (const result of results) {
         if (result.status === 'rejected') {
             console.warn(`⚠️ Promise rejected: ${result.reason}`);
@@ -357,21 +560,22 @@ async function createRepoSnapshot(repoPath, options) {
       }
     }
     
-    snapshotContent += contentArray.join('');
+    // Add the header to the beginning of the file content
+    const repoName = path.basename(absoluteRepoPath);
+    const header = generateSnapshotHeader(stats, repoName, options.aiHeader !== false);
+    snapshotContent = header + snapshotContent + contentArray.join('');
+
     const totalChars = snapshotContent.length;
     const estimatedTokens = Math.round(totalChars / 4);
 
     const timestamp = new Date().toISOString().slice(0, 19).replace('T', '_').replace(/:/g, '-');
-    const repoName = path.basename(absoluteRepoPath);
-    const extension = options.format === 'json' ? 'json' : 'txt';
+    const extension = options.format === 'json' ? 'json' : 'md'; // Changed default to md
     let outputFilename = `${repoName}_snapshot_${timestamp}.${extension}`;
-    
     if (options.compress) {
       outputFilename += '.gz';
     }
 
     const fullOutputFilePath = path.join(absoluteOutputPath, outputFilename);
-
     let finalContent = snapshotContent;
     if (options.format === 'json') {
       const jsonData = {
@@ -383,6 +587,7 @@ async function createRepoSnapshot(repoPath, options) {
           skippedFileTypes: Object.fromEntries(stats.skippedFileTypes),
           skipReasons: Object.fromEntries(stats.skipReasons),
           skippedFilesDetails: Object.fromEntries(
+ 
             Array.from(stats.skippedFilesDetails.entries()).map(([reason, files]) => [
               reason, 
               files.map(({file, ext}) => ({file, ext}))
@@ -395,7 +600,6 @@ async function createRepoSnapshot(repoPath, options) {
     }
 
     await fs.mkdir(absoluteOutputPath, { recursive: true });
-    
     if (options.compress) {
       const compressed = await gzip(finalContent);
       await fs.writeFile(fullOutputFilePath, compressed);
@@ -421,8 +625,7 @@ async function createRepoSnapshot(repoPath, options) {
       console.log('\n📋 Included File Types Distribution:');
       const sortedIncludedTypes = Array.from(stats.includedFileTypes.entries())
         .sort(([,a], [,b]) => b - a)
-        .slice(0, 10); 
-      
+        .slice(0, 10);
       for (const [ext, count] of sortedIncludedTypes) {
         console.log(`  ${ext}: ${count} files`);
       }
@@ -432,8 +635,7 @@ async function createRepoSnapshot(repoPath, options) {
       console.log('\n⏭️  Skipped File Types Distribution:');
       const sortedSkippedTypes = Array.from(stats.skippedFileTypes.entries())
         .sort(([,a], [,b]) => b - a)
-        .slice(0, 10); 
-      
+        .slice(0, 10);
       for (const [ext, count] of sortedSkippedTypes) {
         console.log(`  ${ext}: ${count} files`);
       }
@@ -443,7 +645,6 @@ async function createRepoSnapshot(repoPath, options) {
       console.log('\n📊 Skip Reasons:');
       const sortedReasons = Array.from(stats.skipReasons.entries())
         .sort(([,a], [,b]) => b - a);
-      
       const reasonLabels = {
         'ignored-directory': 'Ignored directories',
         'ignored-extension': 'Ignored extensions',
@@ -454,7 +655,6 @@ async function createRepoSnapshot(repoPath, options) {
         'file-too-large': 'Files too large',
         'read-error': 'Read errors'
       };
-      
       for (const [reason, count] of sortedReasons) {
         const label = reasonLabels[reason] || reason;
         console.log(`  ${label}: ${count} files`);
@@ -471,7 +671,7 @@ async function createRepoSnapshot(repoPath, options) {
             console.log(`    ... and ${files.length - 10} more files`);
           }
         }
-        console.log(); 
+        console.log();
       }
     }
 
@@ -486,7 +686,6 @@ async function createRepoSnapshot(repoPath, options) {
     }
     
     console.log('='.repeat(50));
-    
   } catch (error) {
     console.error('\n❌ An error occurred:');
     if (error.code === 'ENOENT' && error.path && error.path.includes('.git')) {
@@ -509,115 +708,170 @@ 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;
+      }
+    }
 
-    // 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,
-        },
-      ]);
+    // 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.');
+        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);
+    if (progressBar) progressBar.start(filesToRestore.length, 0);
 
-    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 +885,48 @@ 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();
@@ -638,14 +934,14 @@ const program = new Command();
 program
   .name('eck-snapshot')
   .description('A CLI tool to create and restore single-file text snapshots of a Git repository.')
-  .version('2.1.0');
+  .version('3.0.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(process.cwd(), 'snapshots'))
+.option('-o, --output <dir>', 'Output directory for the snapshot file.', path.join(__dirname, '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')
@@ -654,17 +950,22 @@ program
   .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')
+  .option('--format <type>', 'Output format: md, json', 'md')
+  .option('--no-ai-header', 'Skip AI instruction header (create clean snapshot)')
+  .option('-d, --dir', 'Directory mode: scan directory recursively (auto-enabled if no git repo found)')
   .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,7 +1,7 @@
 {
   "name": "@xelth/eck-snapshot",
-  "version": "2.1.0",
-  "description": "A CLI tool to create and restore single-file text snapshots of a Git repository.",
+  "version": "3.0.0",
+  "description": "A powerful CLI tool to create and restore single-file text snapshots of Git repositories and directories. Optimized for AI context and LLM workflows.",
   "main": "index.js",
   "type": "module",
   "bin": {
@@ -31,4 +31,4 @@
     "p-limit": "^5.0.0",
     "inquirer": "^9.2.20"
   }
-}
+}