ai-context 1.5.1 → 1.6.2

package/COMMANDS.md

@@ -0,0 +1,371 @@
+# AIContext CLI Reference
+
+Complete command reference for the `cx` CLI tool.
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Basic Commands](#basic-commands)
+- [Output Options](#output-options)
+- [Output Formats](#output-formats)
+- [Incremental Mode](#incremental-mode)
+- [File Filtering](#file-filtering)
+  - [Ignore Patterns](#ignore-patterns)
+  - [Include Patterns](#include-patterns)
+- [Snapshots](#snapshots)
+- [Configuration](#configuration)
+- [Advanced Options](#advanced-options)
+
+---
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g ai-context
+
+# Generate context from current directory
+cx
+
+# Generate from specific directory
+cx ./src
+
+# Generate with a message
+cx -m "feature update"
+```
+
+---
+
+## Basic Commands
+
+| Command | Description |
+|---------|-------------|
+| `cx` | Generate context from current directory |
+| `cx <path>` | Generate context from specific path |
+| `cx <path1> <path2>` | Generate context from multiple paths |
+| `cx -h` | Show basic help |
+| `cx -h --more` | Show detailed help |
+| `cx -v` | Show version |
+
+### Examples
+
+```bash
+cx                              # Current directory
+cx ./src                        # Specific directory
+cx ./lib ./src/main.js          # Multiple paths
+cx ./src -m "auth api"          # With descriptive message
+```
+
+---
+
+## Output Options
+
+| Option | Description |
+|--------|-------------|
+| `-o` | Output to screen (stdout) instead of file |
+| `-t, --tree` | Display directory tree only |
+| `--no-clipboard` | Skip copying to clipboard |
+| `--verbose` | Show detailed progress |
+
+### Examples
+
+```bash
+cx -o                           # Print to screen
+cx -o | head -100               # Pipe to other commands
+cx -t                           # Show tree only
+cx -t ./src ./lib               # Show trees for multiple paths
+cx --verbose                    # See detailed progress
+```
+
+---
+
+## Output Formats
+
+Generate context in different formats using `-f` or `--format`.
+
+| Format | Extension | Description |
+|--------|-----------|-------------|
+| `text` | `.txt` | Plain text (default) |
+| `md` | `.md` | Markdown with tables and code blocks |
+| `json` | `.json` | Structured JSON for programmatic use |
+| `xml` | `.xml` | XML format with CDATA sections |
+
+### Examples
+
+```bash
+cx -f text                      # Plain text (default)
+cx -f md                        # Markdown format
+cx -f json                      # JSON format
+cx -f xml                       # XML format
+cx ./src -f md -m "docs"        # Markdown with message
+```
+
+### Format Details
+
+**Markdown (`-f md`)**
+- Tables for metadata and file info
+- Fenced code blocks with syntax highlighting
+- Clean, readable structure
+
+**JSON (`-f json`)**
+- Structured data with metadata
+- File array with content and stats
+- Ideal for programmatic processing
+
+**XML (`-f xml`)**
+- Valid XML with proper encoding
+- CDATA sections for code content
+- Supports XML-based toolchains
+
+---
+
+## Incremental Mode
+
+Only include files that changed since a specific time or git reference.
+
+| Option | Description |
+|--------|-------------|
+| `--since <time>` | Files changed since time expression |
+| `--git-diff <ref>` | Files changed vs git reference |
+| `--changed` | Files changed since last `cx` run |
+
+### Time Expressions
+
+| Expression | Meaning |
+|------------|---------|
+| `30m` | 30 minutes ago |
+| `2h` | 2 hours ago |
+| `1d` | 1 day ago |
+| `1w` | 1 week ago |
+| `2024-01-15` | Since specific date |
+
+### Examples
+
+```bash
+cx --since 2h                   # Changed in last 2 hours
+cx --since 1d                   # Changed in last day
+cx --since 2024-01-15           # Changed since date
+cx --git-diff main              # Changed vs main branch
+cx --git-diff HEAD~5            # Changed in last 5 commits
+cx --changed                    # Changed since last cx run
+```
+
+### Use Cases
+
+- **Daily standups**: `cx --since 1d` - What changed today
+- **PR reviews**: `cx --git-diff main` - Changes in feature branch
+- **Quick updates**: `cx --changed` - Only new changes
+
+---
+
+## File Filtering
+
+### Ignore Patterns
+
+Exclude files matching glob patterns.
+
+| Command | Description |
+|---------|-------------|
+| `cx ignore <pattern>` | Add ignore pattern |
+| `cx ignore rm <pattern>` | Remove pattern |
+| `cx ignore show` | List all patterns |
+| `cx ignore clear` | Remove all patterns |
+| `cx ignore test` | Preview excluded files |
+
+### Examples
+
+```bash
+cx ignore "*.log"               # Exclude log files
+cx ignore "dist/**"             # Exclude dist directory
+cx ignore "**/*.test.js"        # Exclude test files
+cx ignore rm "*.log"            # Remove pattern
+cx ignore show                  # List patterns
+cx ignore test                  # Preview exclusions
+```
+
+### Include Patterns
+
+Whitelist files - only matching files are processed.
+
+| Command | Description |
+|---------|-------------|
+| `cx include <pattern>` | Add include pattern |
+| `cx include rm <pattern>` | Remove pattern |
+| `cx include show` | List all patterns |
+| `cx include clear` | Remove all patterns |
+
+### Examples
+
+```bash
+cx include "src/**/*.ts"        # Only TypeScript in src/
+cx include "*.js"               # Only JavaScript files
+cx include "lib/**"             # Only files in lib/
+cx include rm "*.js"            # Remove pattern
+cx include show                 # List patterns
+cx include clear                # Reset to include all
+```
+
+### Pattern Syntax
+
+| Pattern | Matches |
+|---------|---------|
+| `*.js` | All .js files |
+| `**/*.ts` | All .ts files (recursive) |
+| `src/**` | Everything in src/ |
+| `*.{js,ts}` | .js and .ts files |
+| `!*.test.js` | Negation (exclude) |
+
+### How Filtering Works
+
+**Precedence Rules:**
+1. System exclusions always apply first (node_modules, .git, binaries)
+2. `.gitignore` patterns are applied next
+3. **Include patterns** act as a whitelist (if defined)
+4. **Ignore patterns** exclude from the remaining files
+
+**In Practice:**
+- If **no include patterns**: all non-excluded files are processed
+- If **include patterns defined**: only matching files are considered
+- **Ignore patterns** can then further exclude from included files
+- Files must match include AND not match ignore to be processed
+
+**Example:**
+```bash
+cx include "src/**"         # Only files in src/
+cx ignore "**/*.test.js"    # But exclude test files
+# Result: All files in src/ except test files
+```
+
+---
+
+## Snapshots
+
+Create point-in-time captures of your codebase.
+
+| Option | Description |
+|--------|-------------|
+| `-s, --snap` | Create a snapshot |
+
+### Examples
+
+```bash
+cx -s                           # Create snapshot
+cx -s -m "before refactor"      # Snapshot with message
+cx -s -f json                   # Snapshot in JSON format
+```
+
+### Storage
+
+- Regular context: `.aicontext/code/`
+- Snapshots: `.aicontext/snapshots/`
+- Latest file: `.aicontext/latest-context.txt`
+
+---
+
+## Configuration
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `cx configure` | Interactive configuration |
+| `cx show` | Show current settings |
+
+### Settings
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| Auto-clipboard | Copy to clipboard automatically | Off |
+| Timeout | File search timeout | 30s |
+| Max file size | Maximum file size to include | 1MB |
+
+### Examples
+
+```bash
+cx configure                    # Interactive setup
+cx show                         # View current config
+```
+
+### Configuration Files
+
+| File | Purpose |
+|------|---------|
+| `~/.aicontext/config.json` | Global settings |
+| `.aicontext/ignore.json` | Project patterns |
+
+---
+
+## Advanced Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--timeout <sec>` | File search timeout | 30 |
+| `--max-size <MB>` | Max file size | 1 |
+| `--clear` | Remove generated context files | - |
+| `--clear-all` | Remove ALL context files (with confirmation) | - |
+
+### Examples
+
+```bash
+cx --timeout 60                 # Longer timeout for large projects
+cx --max-size 5                 # Include larger files
+cx --clear                      # Clean up code/ directory
+cx --clear-all                  # Clean up everything
+```
+
+---
+
+## Default Exclusions
+
+These are automatically excluded:
+
+- **Directories**: `node_modules`, `.git`, `dist`, `build`, `coverage`, etc.
+- **Files**: Lock files, OS files (`.DS_Store`), IDE configs
+- **Binary files**: Images, executables, archives, media files
+- **Large files**: Files exceeding max-size limit
+
+---
+
+## Tips
+
+1. **Add `.aicontext` to `.gitignore`** to keep generated files local
+2. **Use snapshots** before major refactors
+3. **Combine filters**: `cx --since 1d -f md` for daily markdown reports
+4. **Use include patterns** for focused context on specific file types
+5. **Use `cx -o | head`** to preview output before generating
+
+---
+
+## Quick Reference Card
+
+```bash
+# Core
+cx                      # Generate from current dir
+cx ./src                # Generate from path
+cx -m "message"         # Add filename message
+
+# Output
+cx -o                   # To screen
+cx -t                   # Tree only
+cx -f md                # Markdown format
+cx -f json              # JSON format
+
+# Incremental
+cx --since 2h           # Last 2 hours
+cx --git-diff main      # Vs main branch
+cx --changed            # Since last run
+
+# Filtering
+cx ignore "*.log"       # Exclude pattern
+cx include "*.ts"       # Include only pattern
+cx ignore show          # List ignore patterns
+cx include show         # List include patterns
+
+# Snapshots
+cx -s                   # Create snapshot
+cx -s -m "backup"       # With message
+
+# Config
+cx configure            # Setup
+cx show                 # View settings
+```

package/README.md

@@ -3,246 +3,91 @@
   <h3>Context Management for AI-Assisted Development</h3>
 </div>
 
-📢 **Latest Update (v1.5.0)**: Improved ignore command UX - add patterns directly with `cx ignore "pattern"`, remove with `cx ignore rm "pattern"`. All file types (including .js/.txt) now respect ignore patterns. [See all updates](UPDATES.md)
-
-## Test Status 🧪
-
-[![Test Status](https://img.shields.io/badge/tests-33%20passed-brightgreen.svg)](TESTS.md)
-[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](TESTS.md)
-[![npm](https://img.shields.io/badge/npm-v1.5.1-blue)](https://www.npmjs.com/package/ai-context)
-[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
-[![node](https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen)](package.json)
-
-Last tested: 02/03/2026, 09:40 America/Los_Angeles
+[![Tests](https://img.shields.io/badge/tests-44%20passed-brightgreen.svg)](TESTS.md)
+[![npm](https://img.shields.io/badge/npm-v1.6.2-blue)](https://www.npmjs.com/package/ai-context)
+[![node](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](package.json)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
 ## What is AIContext?
 
-A CLI tool that generates structured context from your codebase for AI tools. It scans your project, filters out build artifacts and binary files, and creates a formatted output that maintains code relationships and project structure. The tool handles file exclusions through `.gitignore` integration and custom ignore patterns.
-
-Run `cx` in your project:
+A CLI tool that generates structured context from your codebase for AI tools. Scans your project, filters out noise, and creates formatted output ready for Claude, ChatGPT, or any AI assistant.
 
 <div align="center">
   <img src="static/cx-example.gif" alt="AI Context Example" width="600" height="auto">
 </div>
 
-## ✨ Key Features
-
-- Automatically excludes binary files, build artifacts, and other non-essential files
-- Create point-in-time snapshots of your codebase
-- Easily exclude specific files or directories with glob patterns
-- Automatically copy context to clipboard (configurable)
-- Includes a visual representation of your project structure
-
-## 🚀 Quick Start
+## Quick Start
 
-Install globally
 ```bash
 npm install -g ai-context
-```
-
-**Upgrading from `aicontextjs`?** If you have the old package installed:
-```bash
-npm uninstall -g aicontextjs
-npm install -g ai-context
-# Or force overwrite: npm install -g ai-context --force
-```
-Generate context from current directory
-```bash
 cx
 ```
-Generate context from specific directory with a message
-```bash
-cx ./src -m "authentication api"
-```
 
-The output will be copied to your clipboard and saved to a context file, ready to paste into your AI tool of choice.
+## Core Commands
 
-## 📋 Command Reference
-
-```
-Usage: cx [directory] [options]
+```bash
+cx                      # Generate from current directory
+cx ./src                # Generate from path
+cx -m "feature"         # Add filename message
+cx -o                   # Output to screen
+cx -t                   # Tree only
+cx -s                   # Create snapshot
 ```
 
-### Basic Commands
-
-| Option | Description |
-|--------|-------------|
-| `-h, --help` | Show help information. Use `-h --more` for detailed help |
-| `configure` | Configure settings |
-| `show` | Show current configuration |
-| `ignore` | Manage ignore patterns |
-| `-v, --version` | Show the current version of the tool |
-| `--clear` | Remove all generated context files inside the ./code folder |
-| `--clear-all` | Remove ALL context files and directories (with confirmation) |
-
-### Context Generation Options
-
-| Option | Description |
-|--------|-------------|
-| `-m, --message "text"` | Add a descriptive message to the context file name |
-| `-s, --snap` | Create a snapshot in the .aicontext/snapshots directory |
-| `-o` | Output directly to screen (supports piping, bypasses file creation) |
-| `-t, --tree` | Display directory tree only |
-| `--verbose` | Show detailed progress during execution |
-| `--no-clipboard` | Skip copying content to clipboard |
-
-### File Filtering Options
-
-| Option | Description |
-|--------|-------------|
-| `ignore <pattern>` | Add a glob pattern to exclude files/directories |
-| `ignore rm <pattern>` | Remove an exclusion pattern |
-| `ignore show` | Display all current exclusion patterns |
-| `ignore clear` | Remove all exclusion patterns |
-| `ignore test` | Test the exclusions by showing directory tree |
-| `--timeout <seconds>` | Set a custom timeout (default: 10 seconds) |
-| `--max-size <MB>` | Set a custom maximum file size (default: 1 MB) |
-
-### Examples
+## Output Formats
 
 ```bash
-# Basic context generation
-cx                           # Generate context from current directory
-cx ./src                     # Generate context from specific directory
-cx ./src -m "auth api"       # Add a descriptive message to the context
-
-# Direct output and piping
-cx -o                        # Output directly to screen
-cx ./src -o                  # Output specific directory to screen
-cx ./src -o | grep "func"   # Pipe output to grep for filtering
-cx -o | head -n 50          # Show first 50 lines of context
-
-# Snapshots
-cx ./src -s                  # Create a snapshot
-cx -s -m "before refactor"   # Create snapshot with message
-
-# Directory tree
-cx -t                        # Show directory tree for current directory
-cx -t ./src ./lib           # Show trees for multiple paths
-
-# Configuration and ignore patterns
-cx configure                 # Configure settings
-cx show                     # Show current configuration
-cx ignore "*.log"           # Add ignore pattern
-cx ignore rm "*.log"        # Remove ignore pattern
-cx ignore show              # Show all patterns
-cx ignore clear             # Remove all patterns
-
-# Performance options
-cx --verbose                # Show detailed progress
-cx --timeout 10            # Set a shorter timeout of 10 seconds
-cx --max-size 20           # Set a custom maximum file size of 20 MB
-cx --no-clipboard          # Skip clipboard operations
-
-# Clean up
-cx --clear                 # Remove all generated context files (except snapshots)
-cx --clear-all            # Remove ALL context files and directories (with confirmation)
+cx -f text              # Plain text (default)
+cx -f md                # Markdown
+cx -f json              # JSON
+cx -f xml               # XML
 ```
 
-## 📋 Configuration
-
-Use `cx configure` to set up your preferences for a customized experience:
-
-### Available Configuration Options:
-
-| Setting | Description |
-|---------|-------------|
-| **Auto-clipboard copy** | Enable/disable automatic copying of generated context to clipboard |
-| **Default timeout** | Set the default timeout in seconds for scanning directories (default: 10s) |
-| **Max file size** | Set the maximum file size in MB to include in context (default: 1MB) |
-
-These settings help you customize how AIContext operates to match your workflow. For example, disabling clipboard copy can speed up execution, while adjusting timeout and file size limits can help with larger projects.
+## Incremental Mode
 
-View your current configuration with `cx show`.
-
-Configuration is stored in `~/.aicontext/config.json` and can be manually edited if needed.
-
-## 🚫 File Exclusions & Ignore Patterns
-
-AIContext intelligently manages which files to include in your context:
-
-### Default Exclusions
-
-The following are automatically excluded:
-- Binary files (executables, object files, media files)
-- Common build directories (`node_modules`, `dist`, `.git`, etc.)
-- Files larger than the configured size limit (default: 1MB)
-- Compressed archives (`.zip`, `.tar.gz`, etc.)
-
-### Managing Custom Exclusions
-
-Use the `ignore` command to manage your exclusion patterns:
+Only include changed files:
 
 ```bash
-# Add exclusion patterns
-cx ignore "*.log"              # Exclude all log files
-cx ignore "build/**"           # Exclude build directory
-cx ignore "**/*.min.js"        # Exclude all minified JS files
-
-# Remove a pattern
-cx ignore rm "*.log"           # Remove the *.log pattern
-
-# View and manage patterns
-cx ignore show                 # List current patterns
-cx ignore test                 # Preview what will be excluded
-cx ignore clear                # Remove all patterns
+cx --since 2h           # Last 2 hours
+cx --since 1d           # Last day
+cx --git-diff main      # vs main branch
+cx --changed            # Since last run
 ```
 
-### Pattern Types
-
-- **Simple patterns**: `*.log`, `*.tmp`
-- **Directory patterns**: `build/**`, `temp/*`
-- **Path-based**: `./src/tests/**`
-- **Multiple extensions**: `*.{jpg,png,gif}`
-
-### Configuration Files
-
-- Project-specific exclusions: `.aicontext/ignore.json`
-- Global exclusions: `~/.aicontext/config.json`
-
-Tip: Add `.aicontext` to your `.gitignore` if you don't want to share exclusion patterns with your team.
+## File Filtering
 
-## 💡 Best Practices
-
-1. Add the 'context' folder to your .gitignore file
-2. Use meaningful messages for better organization
-3. Create snapshots before major changes
-4. Clear old context files regularly with `cx --clear`
-5. Use the latest-context.txt file for AI tools integration
-
-## 📝 Updates
-
-See [UPDATES.md](UPDATES.md) for a history of changes and new features.
-
-## 🤝 Need Help?
-
-AIContext includes several ways to get help:
-
-### Built-in Help
 ```bash
-# Basic help
-cx -h
+# Exclude patterns
+cx ignore "*.log"
+cx ignore show
 
-# Detailed help with all options
-cx -h --more
+# Include patterns (whitelist)
+cx include "src/**/*.ts"
+cx include show
 ```
 
-### Verbose Mode
-For troubleshooting issues, use verbose mode to see detailed output:
+## Configuration
+
 ```bash
-cx --verbose        # Show detailed processing information
+cx configure            # Setup
+cx show                 # View settings
 ```
 
-### Timeout Issues
-If you're getting timeout errors with large projects:
+## Full Documentation
+
+**[COMMANDS.md](COMMANDS.md)** - Complete CLI reference with all options, examples, and patterns.
+
+## Help
+
 ```bash
-cx --timeout 60    # Increase timeout to 60 seconds
+cx -h                   # Basic help
+cx -h --more            # Detailed help
 ```
 
-### Contributing & Issues
-- Report bugs and suggest features on [GitHub Issues](https://github.com/csanz/aictx/issues)
-- For questions, use [GitHub Discussions](https://github.com/csanz/aictx/discussions)
+- [Updates](UPDATES.md) - Version history
+- [Issues](https://github.com/csanz/aicontext/issues) - Report bugs
+- [Discussions](https://github.com/csanz/aicontext/discussions) - Questions
 
-## 📄 License
+## License
 
 MIT