@xelth/eck-snapshot 3.0.0 → 4.1.0

package/README.md

@@ -1,292 +1,120 @@
-# eck-snapshot
-
-[![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 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 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.
-
-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.
-
-## 🚀 Key Features
-
-### 📁 **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
-
-### 🤖 **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
-
-### ⚡ **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
-
-## 📦 Installation
-
-```bash
-npm install -g @xelth/eck-snapshot
-```
-
-## 🎯 Quick Start
-
-### Create Snapshots
-
-```bash
-# Git repository (default mode)
-eck-snapshot
-
-# Any directory (auto-detects non-git folders)
-eck-snapshot /path/to/any/folder
-
-# Force directory mode (ignores git)
-eck-snapshot --dir .
-
-# Clean snapshot without AI instructions
-eck-snapshot --no-ai-header
-
-# Compressed JSON format
-eck-snapshot --format json --compress
-```
-
-### Restore from Snapshots
-
-```bash
-# Basic restore
-eck-snapshot restore snapshot.md
-
-# Restore to specific directory
-eck-snapshot restore snapshot.md ./restored-project
-
-# Preview without writing files
-eck-snapshot restore snapshot.md --dry-run
-
-# Restore only specific files
-eck-snapshot restore snapshot.md --include "*.js" "*.json"
-```
-
-## 📋 Usage Examples
-
-### For AI Development
-
-```bash
-# Create AI-optimized snapshot for Gemini/Claude
-eck-snapshot --format md --compress
-# Result: project_snapshot_2025-01-19_12-00-00.md.gz
-
-# Clean snapshot for general documentation
-eck-snapshot --no-ai-header --output ./docs
-```
-
-### Project Backup & Migration
-
-```bash
-# Full project backup
-eck-snapshot --include-hidden --format json --compress
-
-# Selective restore
-eck-snapshot restore backup.json.gz --exclude "node_modules/*" --include "src/*"
-```
-
-### Cross-Platform Development
-
-```bash
-# Create snapshot on Windows
-eck-snapshot --output ./transfer
-
-# Restore on Linux/Mac
-eck-snapshot restore transfer/project_snapshot.md ./project
-```
-
-## ⚙️ Configuration
-
-Create `.ecksnapshot.config.js` in your project root:
-
-```javascript
-export default {
-  // Files to ignore by name or pattern
-  filesToIgnore: [
-    'package-lock.json',
-    '*.log',
-    '*.tmp'
-  ],
-  
-  // File extensions to ignore
-  extensionsToIgnore: [
-    '.sqlite3',
-    '.env',
-    '.DS_Store',
-    '.ico',
-    '.png',
-    '.jpg'
-  ],
-  
-  // Directories to ignore
-  dirsToIgnore: [
-    'node_modules/',
-    '.git/',
-    'dist/',
-    'build/',
-    'coverage/'
-  ],
-  
-  // Size and performance limits
-  maxFileSize: '10MB',
-  maxTotalSize: '100MB',
-  maxDepth: 10,
-  concurrency: 10
-};
-```
-
-## 📖 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
-
-- **Issues**: [GitHub Issues](https://github.com/xelth-com/eckSnapshot/issues)
-- **Documentation**: This README and `--help` commands
-- **Examples**: See the examples directory in the repository
+
+# eckSnapshot
+
+A lightweight, platform-independent CLI for creating focused, AI-ready project snapshots.
+
+`eckSnapshot` is a powerful command-line tool designed to solve a critical problem in AI-assisted development: providing clear, complete, and focused context to Large Language Models (LLMs). It allows you to package an entire project codebase—or just specific parts of it—into a single, clean text file.
+
+This tool is built for a modern workflow where you act as the architect, guiding the overall strategy, while AI agents handle the detailed implementation.
+
+## The Core Workflow
+
+`eckSnapshot` is designed to support a two-part AI workflow for maximum efficiency and quality:
+
+1.  **The Architect LLM (Gemini, GPT-4, Grok):** A model with a large context window. You provide it with a snapshot of your project, and it analyzes the codebase to create a high-level plan for new features or refactoring.
+2.  **The Coder LLM (Claude Code, OpenAI Codex):** A model specialized in writing and modifying code. It takes the detailed instructions generated by the Architect and performs the hands-on coding tasks.
+
+## Requirements
+
+1.  **Node.js** (v18.x or higher).
+2.  **An AI Assistant CLI (at least one):**
+    *   **Claude:** An active **Claude Pro** subscription and the `claude-code` CLI installed.
+    *   **OpenAI:** An active **ChatGPT Plus/Pro** subscription and the `@openai/codex` CLI installed (`npm install -g @openai/codex`).
+
+## Installation
+
+Install `eckSnapshot` globally on your system using npm:
+
+```bash
+npm install -g @xelth/eck-snapshot
+```
+
+Once installed, you can run the tool using the `eck-snapshot` command from any directory.
+
+## A Step-by-Step Guide to Using eckSnapshot
+
+Here’s the most common workflow, from creating a full snapshot to focusing on specific features.
+
+#### Step 1: Create a Full Project Snapshot
+
+This is your primary command. It scans your project and packs all relevant code into a single file.
+
+> **Usage:**
+> ```bash
+> dimi@xelth:/mnt/c/Users/xelth/myProject$ eck-snapshot
+> ```
+
+*   **What it does:** Creates a file like `myProject_snapshot_... .md` in the `.eck/snapshots/` directory. This file contains your project's directory structure and the complete code. You can now pass this file to your Architect LLM for analysis.
+
+#### Step 2: Handle Large Projects with Auto-Profiling
+
+If your project is too large for an LLM's context window, `profile-detect` can automatically slice it into logical parts (profiles) using AI.
+
+> **Usage:**
+> ```bash
+> dimi@xelth:/mnt/c/Users/xelth/myProject$ eck-snapshot profile-detect
+> ```
+
+*   **Output Example:**
+    ```
+    ✨ Detected Profiles:
+    ---------------------------
+      - cli
+      - services
+      - core
+      - templates
+      - docs
+      - config
+    ```
+*   **What it does:** Analyzes your project and saves these logical groupings into a `.eck/profiles.json` file, which you can use in the next step.
+
+#### Step 3: Use Profiles to Create Focused Snapshots
+
+The `--profile` option gives you powerful control over what goes into a snapshot. You can combine profiles, exclude files, and even use ad-hoc patterns.
+
+> **Example 1: Combine and Exclude Profiles**
+>
+> Create a snapshot of the core logic, services, and CLI, but exclude all documentation and configuration files.
+> ```bash
+> eck-snapshot --profile "core,services,cli,-docs,-config"
+> ```
+
+> **Example 2: Use Ad-Hoc Glob Patterns**
+>
+> Include all `.js` files in the `src` directory but exclude all test files, without using a pre-defined profile.
+> ```bash
+> eck-snapshot --profile "src/**/*.js,-**/*.test.js"
+> ```
+> *Note: Quotes are required when using complex patterns with wildcards (`*`) or commas.*
+
+#### Step 4: Intelligently Prune a Snapshot
+
+If a snapshot is still too large, `prune` uses AI to shrink it to a target size, keeping only the most important files for understanding the code.
+
+> **Usage:**
+> ```bash
+> eck-snapshot prune myProject_snapshot.md --target-size 500KB
+> ```
+
+#### Step 5 (Alternative): Truncate Files by Line Count
+
+A faster, non-AI method to reduce snapshot size. This command keeps only the top N lines of each file, which is useful for a high-level architectural overview.
+
+> **Usage:**
+> ```bash
+> eck-snapshot --max-lines-per-file 200
+> ```
+
+## Auxiliary Commands
+
+*   `restore <snapshot_file>`: Recreates a project's file structure from a snapshot.
+*   `generate-profile-guide`: Creates a guide for manual profile creation. Use this if `profile-detect` fails on very large projects, as it allows you to use an LLM with a larger context window (e.g., a web UI).
+*   `detect`: Shows how `eckSnapshot` has identified your project type and what default file filters are being applied.
+*   `ask-gpt` / `ask-claude`: Directly delegate a task to your configured AI coder agents from the command line.
+*   `setup-gemini`: A utility to automatically configure integration with the `gemini-cli`.
+
+For a full list of commands and options, run `eck-snapshot --help`.
+
+## License
+
+This project is licensed under the MIT License.