@xelth/eck-snapshot 2.2.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

@@ -3,140 +3,124 @@
 [![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.
 
-## Why eck-snapshot?
+## ✨ What's New in v3.0.0
 
-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.
+🎯 **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  
 
-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.
+## Why eck-snapshot?
 
-## Key Features
+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.
 
-  * **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.
+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.
 
-## Demo
+## 🚀 Key Features
 
-Here's an example of `eck-snapshot` in action:
+### 📁 **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
 
-```
-🚀 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
-...
-==================================================
-```
+### 🤖 **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
 
-The beginning of the generated file will look like this:
+### ⚡ **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
 
-```text
-Directory Structure:
+### 🔒 **Security & Performance**
+- **Path Validation**: Prevents directory traversal attacks
+- **Parallel Processing**: Concurrent file handling for speed
+- **Memory Efficient**: Handles large projects without memory issues
 
-├── .github/
-│   └── workflows/
-│       └── publish.yml
-├── src/
-│   ├── utils/
-│   │   └── formatters.js
-│   └── index.js
-├── .gitignore
-├── package.json
-└── README.md
+## 📦 Installation
 
+```bash
+npm install -g @xelth/eck-snapshot
+```
 
---- File: /src/index.js ---
+## 🎯 Quick Start
 
-#!/usr/bin/env node
-import { Command } from 'commander';
-// ... rest of the file content
+### Create Snapshots
 
---- File: /package.json ---
+```bash
+# Git repository (default mode)
+eck-snapshot
 
-{
-  "name": "eck-snapshot",
-  "version": "2.1.0",
-  // ... rest of the file content
-```
+# Any directory (auto-detects non-git folders)
+eck-snapshot /path/to/any/folder
 
-## Installation
+# Force directory mode (ignores git)
+eck-snapshot --dir .
 
-To install the tool globally, run the following command:
+# Clean snapshot without AI instructions
+eck-snapshot --no-ai-header
 
-```bash
-npm install -g @xelth/eck-snapshot
+# Compressed JSON format
+eck-snapshot --format json --compress
 ```
 
-## Usage
-
-Once installed, you can run the tool from any directory in your terminal.
-
-### Creating a Snapshot
+### Restore from Snapshots
 
 ```bash
-# Create a snapshot of the current directory
-eck-snapshot
+# Basic restore
+eck-snapshot restore snapshot.md
 
-# Specify a path to another repository
-eck-snapshot /path/to/your/other/project
+# Restore to specific directory
+eck-snapshot restore snapshot.md ./restored-project
 
-# Save the snapshot to a different directory and exclude the tree view
-eck-snapshot --output ./backups --no-tree
+# Preview without writing files
+eck-snapshot restore snapshot.md --dry-run
 
-# 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
+# Restore only specific files
+eck-snapshot restore snapshot.md --include "*.js" "*.json"
 ```
 
-### Restoring from a Snapshot
+## 📋 Usage Examples
+
+### For AI Development
 
 ```bash
-# Basic restore to current directory
-eck-snapshot restore ./snapshots/project_snapshot_...txt
+# Create AI-optimized snapshot for Gemini/Claude
+eck-snapshot --format md --compress
+# Result: project_snapshot_2025-01-19_12-00-00.md.gz
 
-# Restore to a specific directory without confirmation
-eck-snapshot restore snapshot.txt ./restored-project --force
+# Clean snapshot for general documentation
+eck-snapshot --no-ai-header --output ./docs
+```
 
-# Preview what would be restored (dry run)
-eck-snapshot restore snapshot.txt --dry-run
+### Project Backup & Migration
 
-# Restore only specific files using patterns
-eck-snapshot restore snapshot.txt --include "*.js" "*.json"
+```bash
+# Full project backup
+eck-snapshot --include-hidden --format json --compress
 
-# Restore everything except certain files
-eck-snapshot restore snapshot.txt --exclude "*.log" "node_modules/*"
+# Selective restore
+eck-snapshot restore backup.json.gz --exclude "node_modules/*" --include "src/*"
+```
 
-# Restore with custom concurrency and verbose output
-eck-snapshot restore snapshot.txt --concurrency 20 --verbose
+### Cross-Platform Development
 
-# Restore compressed snapshots
-eck-snapshot restore project_snapshot.txt.gz ./restored
-```
+```bash
+# Create snapshot on Windows
+eck-snapshot --output ./transfer
 
-## Configuration
+# 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 {
@@ -144,19 +128,29 @@ 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/'
   ],
-  // Size and performance settings
+  
+  // Size and performance limits
   maxFileSize: '10MB',
   maxTotalSize: '100MB',
   maxDepth: 10,
@@ -164,63 +158,135 @@ export default {
 };
 ```
 
-## Advanced Features
+## 📖 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
 
-### Restore Command Options
+**Format & Compression:**
+- `--format <type>` - Output format: md (default) or json
+- `--compress` - Create gzipped output (.gz extension)
+- `--no-tree` - Exclude directory tree from output
 
-The restore command offers powerful filtering and control options:
+**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
 
-- **`--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
+### Restore Command
 
-### Supported Formats
+```bash
+eck-snapshot restore [options] <snapshot_file> [target_directory]
+```
 
-- **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
+**Control Options:**
+- `-f, --force` - Skip confirmation prompts
+- `--dry-run` - Preview without writing files
+- `-v, --verbose` - Show detailed processing information
 
-### Security Features
+**Filtering:**
+- `--include <patterns>` - Include only matching files (wildcards supported)
+- `--exclude <patterns>` - Exclude matching files (wildcards supported)
+- `--concurrency <number>` - Number of concurrent operations (default: 10)
 
-- **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)
+## 🎭 Working with AI Models
 
-## Command Reference
+### 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.
 
-### Snapshot Command
+### For Claude Code
+```bash
+# Clean, focused snapshot
+eck-snapshot --no-ai-header --max-total-size 200MB
+```
+
+### For ChatGPT/Other Models
 ```bash
-eck-snapshot [options] [repoPath]
+# Standard snapshot with moderate size limits
+eck-snapshot --max-total-size 50MB --no-ai-header
 ```
 
-**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
+## 🔧 Advanced Use Cases
 
-### Restore Command
+### Monorepo Support
 ```bash
-eck-snapshot restore [options] <snapshot_file> [target_directory]
+# 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
 ```
 
-**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
+### 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.
 
-## License
+## 📞 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')) {
@@ -512,7 +711,6 @@ async function createRepoSnapshot(repoPath, options) {
 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}`);
 
@@ -563,7 +761,6 @@ async function restoreSnapshot(snapshotFile, targetDir, options) {
     }
 
     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 => {
@@ -580,7 +777,6 @@ async function restoreSnapshot(snapshotFile, targetDir, options) {
         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;
@@ -588,21 +784,18 @@ async function restoreSnapshot(snapshotFile, targetDir, options) {
     }
 
     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);
@@ -616,6 +809,7 @@ async function restoreSnapshot(snapshotFile, targetDir, options) {
           await fs.writeFile(fullPath, file.content, 'utf-8');
           
           stats.restoredFiles++;
+ 
           
           if (progressBar) {
             progressBar.update(index + 1);
@@ -624,6 +818,7 @@ async function restoreSnapshot(snapshotFile, targetDir, options) {
           }
           
           return { success: true, file: file.path };
+ 
         } catch (error) {
           stats.failedFiles++;
           stats.errors.push({ file: file.path, error: error.message });
@@ -632,6 +827,7 @@ async function restoreSnapshot(snapshotFile, targetDir, options) {
             console.log(`❌ Failed to restore: ${file.path} - ${error.message}`);
           }
           
+     
           return { success: false, file: file.path, error: error.message };
         }
       })
@@ -658,7 +854,6 @@ async function restoreSnapshot(snapshotFile, targetDir, options) {
     }
     console.log(`📁 Target directory: ${absoluteTargetDir}`);
     console.log('='.repeat(50));
-
   } catch (error) {
     console.error('\n❌ An error occurred during restore:');
     console.error(error.message);
@@ -673,7 +868,6 @@ 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] || '';
@@ -695,7 +889,8 @@ function filterFilesToRestore(files, options) {
   let filtered = files;
   
   if (options.include) {
-    const includePatterns = Array.isArray(options.include) ? options.include : [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, '.*'));
@@ -719,10 +914,8 @@ function filterFilesToRestore(files, options) {
 
 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') ||
@@ -741,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')
@@ -757,7 +950,9 @@ 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));
 
 program

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xelth/eck-snapshot",
-  "version": "2.2.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": {