claude-code-automation/README.md

🚀 Generic project automation system with anti-compaction protection and recovery capabilities. Automatically detects project type (React, Node.js, Python, Rust, Go, Java) and provides intelligent analysis. Claude Code optimized - run 'welcome' after inst

# Code Automation 🚀

**Universal anti-compaction system with perfect recovery capabilities for Claude Code projects**

> ⚠️ **Note**: This package is specifically designed for Claude Code AI assistant sessions and will not work with other AI tools (ChatGPT, Copilot, Cursor, etc.).

[![npm version](https://badge.fury.io/js/claude-code-automation.svg)](https://badge.fury.io/js/claude-code-automation)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 🌟 Latest Features (v3.0.6)

### 🐛 **FIXED: Critical Installation Bug (v3.0.6)**
- **✅ Complete File Installation** - Fixed missing anti-truncation-guard.js file during installation
- **🛠️ All NPM Scripts Work** - Users can now run all automation commands without module errors
- **🎯 Immediate Fix** - Resolves "Cannot find module" error for automation:guard command

### 🐛 **FIXED: Installation Issues (v3.0.2)**
- **✅ Reliable Installation** - Fixed critical bug where automation files weren't copied
- **🔍 Enhanced Error Reporting** - Clear feedback when installation fails
- **📊 Detailed Logging** - See exactly what's happening during installation
- **⚡ Fail-Fast Behavior** - Installation stops immediately with helpful error messages

### 🔒 **Enterprise Security (v3.0.0)** 
- **🛡️ SecureProcessManager** - Enterprise-grade process security system
- **⚔️ Command Injection Prevention** - Blocks dangerous shell patterns (`;`, `&&`, `||`, `|`, etc.)
- **📊 Resource Limits** - Process count (5 max), memory (512MB), timeout (2min) enforcement
- **🔐 Process Isolation** - Secure project-level process management
- **🎯 Command Whitelisting** - Only allow safe npm, git, node operations
- **📱 Verbose Mode** - `--verbose` flag for detailed operation feedback

### 🧠 **Core Features**
- **🛡️ Anti-Truncation Guard** - Prevents context truncation in real-time
- **🔍 Compaction Risk Analyzer** - Predicts and prevents compaction events  
- **⚡ Live Preservation Engine** - Continuous context monitoring
- **🎯 Advanced Recovery System** - Comprehensive project reconstruction
- **📊 Development Session Tracker** - Maintains session continuity
- **🧠 Enhanced Context Analysis** - Deep project understanding

## 🎯 The Problem This Solves

**Context Loss** is the #1 problem when working with Claude Code:
- ❌ Long sessions lose context due to token limits
- ❌ Complex projects get "compacted" and lose detail
- ❌ Recovery is manual and error-prone
- ❌ Progress gets lost between sessions

## ✅ The Solution

**Code Automation** provides:
- ✅ **Fixed critical installation bug** - All automation files now install correctly (v3.0.6)
- ✅ **Fixed installation issues** - Reliable file copying and clear error messages (v3.0.2)
- ✅ **Enterprise-grade security** - Process isolation, command validation, resource limits
- ✅ **Automatic context preservation** every 30 minutes
- ✅ **Advanced project recovery** from any state
- ✅ **Real-time compaction protection**
- ✅ **Professional user experience** with verbose feedback
- ✅ **Zero-configuration setup**
- ✅ **Reliable automation**

## 🚀 Quick Start

### Installation

```bash
# Global installation (recommended)
npm install -g claude-code-automation

# ⚠️ IMPORTANT: NPM doesn't show post-install messages for global packages
# Run this command immediately after install:
welcome

# Or get detailed help
code-automation help

# Or local installation
npm install claude-code-automation --save-dev
```

### Setup Your Project

```bash
# Navigate to your project
cd your-project

# Install automation system
claude-code-automation install

# Start protection immediately (with verbose feedback)
code-automation --verbose preserve

# Or use npm scripts
npm run automation:preserve
```

## 📋 Available Commands

### CLI Commands (Global)
```bash
claude-code-automation install              # Setup in current project
code-automation --verbose preserve  # Preserve current context (with detailed feedback)
code-automation --verbose recover   # Recover from backup (with detailed feedback)
code-automation --verbose analyze   # Analyze project state (with detailed feedback)
preserve                            # Quick preserve (silent)
recover                             # Quick recover (silent)
analyze                             # Quick analyze (silent)
inject                              # Inject into existing project
```

### 🔒 Security Options
```bash
code-automation --verbose [command]  # Enable detailed security feedback
code-automation --quiet [command]    # Suppress non-essential output
```

### NPM Scripts (Project)
```bash
npm run automation:preserve  # Preserve current state
npm run automation:recover   # Recover from latest backup
npm run automation:analyze   # Analyze project health
npm run automation:daily     # Run full automation cycle
npm run automation:guard     # Start anti-truncation guard
```

## 🔧 Core Features

### 🛡️ Anti-Truncation Guard
Prevents context loss before it happens:
```bash
npm run automation:guard
```
- Monitors token usage in real-time
- Triggers preservation before limits
- Maintains conversation continuity

### 🔍 Compaction Risk Analyzer
Predicts when compaction will occur:
- Analyzes conversation patterns
- Calculates risk scores
- Proactive preservation triggers

### ⚡ Live Preservation Engine
Continuous background protection:
- Auto-saves every 30 minutes
- Incremental state updates  
- Zero performance impact

### 🎯 Advanced Recovery System
Comprehensive project restoration:
```bash
recover
# Attempts to restore project state
```
- Reconstructs complete project state
- Restores all decisions and context
- Maintains development history

## 🔒 Enterprise Security (v3.0.0)

### 🛡️ SecureProcessManager
- **Process Isolation**: Each project runs in isolated context
- **Resource Limits**: Max 5 processes, 512MB memory, 2-minute timeouts
- **Command Whitelisting**: Only npm, yarn, pnpm, node, git allowed
- **Input Sanitization**: Blocks dangerous patterns: `;`, `&&`, `||`, `|`, `\``, `$`, `>`, `<`, `&`

### ⚔️ Security Features
```bash
# Secure command execution with validation
code-automation --verbose preserve  # Shows security decisions

# Process resource monitoring
code-automation analyze             # Displays security status

# Safe automation without global process hijacking
npm run automation:daily           # Uses secure process management
```

### 🔐 What's Protected
- ✅ **Command Injection Prevention** - All user input validated
- ✅ **Process Resource Limits** - Prevents system overload
- ✅ **Path Traversal Protection** - Secure file operations only
- ✅ **Process Cleanup** - Automatic resource cleanup on exit
- ✅ **Timeout Enforcement** - No runaway processes

### 🚨 Breaking Changes in v3.0.0
- All process execution now goes through SecureProcessManager
- Stricter command validation may block some edge cases
- Process limits enforced (upgrade from unlimited processes)
- More restrictive input validation for enhanced security

## 📊 Usage Examples

### Basic Project Setup
```bash
# Install globally
npm install -g claude-code-automation

# Setup new project
mkdir my-claude-project
cd my-claude-project
claude-code-automation install

# Start development with protection
npm run automation:preserve
```

### Recovering Lost Context
```bash
# If you lose context during development
recover

# Or use NPM script
npm run automation:recover

# Verify recovery
npm run automation:analyze
```

### Continuous Protection
```bash
# Start anti-truncation guard
npm run automation:guard

# Run daily maintenance
npm run automation:daily

# Check project health
npm run automation:analyze
```

## 🏗️ Architecture

### Core Components
- **Context Preservation Engine** - State capture and storage
- **Auto Recovery System** - Intelligent project reconstruction  
- **Live Preservation Engine** - Real-time monitoring
- **Anti-Truncation Guard** - Proactive protection
- **Compaction Risk Analyzer** - Predictive analysis
- **Development Session Tracker** - Session continuity

### File Structure
```
your-project/
├── scripts/automation/           # Automation scripts
├── docs/automation/             # Generated documentation
├── docs/state/                  # Project state snapshots
├── docs/recovery/               # Recovery instructions
└── package.json                 # Updated with scripts
```

## ⚙️ Configuration

Configuration is automatic, but can be customized:

```json
{
  "version": "1.0.0",
  "enabled": true,
  "features": {
    "contextPreservation": true,
    "antiTruncation": true,
    "livePreservation": true,
    "perfectRecovery": true,
    "riskAnalysis": true,
    "sessionTracking": true
  },
  "settings": {
    "preservationInterval": 1800000,
    "maxBackups": 50,
    "compressionEnabled": true,
    "verboseLogging": false
  }
}
```

## 🧪 Testing

```bash
# Test installation
npm test

# Verify integrity
npm run verify

# Test recovery system
code-automation recover --verify
```

## 📈 Benefits

### For Developers
- ✅ **Never lose progress** again
- ✅ **Seamless session continuity**
- ✅ **Instant project recovery**
- ✅ **Zero maintenance required**

### For Teams
- ✅ **Consistent project state**
- ✅ **Reliable handoffs**
- ✅ **Automated documentation**
- ✅ **Reduced onboarding time**

## 🔄 Upgrading

```bash
# Upgrade globally
npm install -g claude-code-automation@latest

# Update existing projects
cd your-project
claude-code-automation install
```

**Latest features are automatically enabled!**

## 🐛 Troubleshooting

### Common Issues

**Installation fails (Fixed in v3.0.6):**
```bash
# v3.0.6+ ensures all automation files are copied during installation
# v3.0.2+ provides clear error messages if installation fails
claude-code-automation install

# If you see "Failed to copy automation files":
# 1. Check npm permissions
# 2. Try reinstalling the package
npm uninstall -g claude-code-automation
npm install -g claude-code-automation

# Alternative: Use npx
npx claude-claude-code-automation install
```

**Files not copied to .automation/ directory:**
```bash
# v3.0.2+ shows detailed logging during installation
# Look for these messages:
# ✅ Copied: context-preservation.js
# ✅ All 4 automation files copied successfully

# If files are missing, check:
ls -la .automation/
# Should contain: context-preservation.js, auto-recovery.js, etc.
```

**Recovery doesn't work:**
```bash
# Verify backup exists
ls docs/state/

# Force recovery
recover --force

# Check integrity
npm run verify
```

**Context still lost:**
```bash
# Enable verbose logging
npm run automation:preserve -- --verbose

# Check risk analysis
npm run automation:analyze
```

## 📚 Advanced Usage

### Custom Preservation Intervals
```javascript
// In your project
const preservation = require('claude-code-automation');
preservation.setInterval(15 * 60 * 1000); // 15 minutes
```

### Integration with CI/CD
```yaml
# .github/workflows/preserve.yml
name: Context Preservation
on: [push, pull_request]
jobs:
  preserve:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - run: npm install -g claude-code-automation
      - run: preserve
```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

## 📄 License

MIT License - see [LICENSE](LICENSE)