pacc-cli 1.1.2
Package manager for Claude Code - simplify installation and management of Claude Code extensions
License: MIT
Requires Python: >=3.8
Keywords: claude, claude-code, package-manager, extensions, hooks, mcp, agents, commands, cli, developer-tools

# PACC CLI - Package Manager for Claude Code

A Python CLI tool for managing Claude Code extensions including hooks, MCP servers, agents, and slash commands.

**Note on Extension Types:**
- **Hooks & MCP Servers**: Configuration-based, stored in `settings.json`
- **Agents & Commands**: File-based, placed in directories and auto-discovered by Claude Code

## Installation

```bash
# Install from PyPI (recommended)
pip install pacc-cli

# Or install with pipx for isolated environment
pipx install pacc-cli

# For development (from source)
git clone https://github.com/memyselfandm/pacc-cli.git
cd pacc-cli
pip install -e .
```

## Project Status

**🎯 Production Ready - Version 1.1.0** ✅

### ✅ Completed Features
- **Wave 1-4 - MVP Foundation**: Complete core package management with >80% test coverage
- **Phase 0 - Core CLI**: All basic package management commands implemented
- **Phase 1 - Remote Sources**: Git and URL-based installation with security validation
- **Phase 2 - Project Configuration**: Team collaboration via pacc.json project configs
- **Phase 3 - Packaging & Distribution**: Production-ready package with full installation support

### 🚀 CLI Commands Ready for Production
- **`pacc install`**: Install extensions from local sources, Git repos, or URLs
- **`pacc list`**: List installed extensions with filtering and search
- **`pacc remove`**: Safely remove extensions with dependency checking
- **`pacc info`**: Display detailed extension information and metadata
- **`pacc validate`**: Validate extensions without installing

### 🧠 Memory Fragments (NEW in 1.1.0)
- **`pacc fragment install`**: Install context fragments from files, directories, or Git repos
- **`pacc fragment list`**: List installed fragments with filtering
- **`pacc fragment info`**: Display fragment details and metadata
- **`pacc fragment remove`**: Remove fragments with automatic CLAUDE.md cleanup
- **`pacc fragment update`**: Update fragments from their sources
- **`pacc fragment sync`**: Sync team fragments from pacc.json configuration

See the [Fragment User Guide](docs/fragment_user_guide.md) for complete documentation.

### 🤝 Team Collaboration Features
- **`pacc init --project-config`**: Initialize project with shared extension configuration
- **`pacc sync`**: Synchronize extensions from project pacc.json configuration
- **Project Configuration**: pacc.json files for defining team extension standards

### 🔒 Security Features
- **Path Traversal Protection**: Prevents arbitrary file access/deletion via malicious fragment names
- **Input Validation**: All user input is sanitized before file operations
- **Boundary Validation**: Operations restricted to designated storage directories
- **Defense in Depth**: Multiple validation layers for critical operations

## Architecture

### Core Components

#### 1. Foundation Layer (`pacc/core/`)
- **FilePathValidator**: Cross-platform path validation with security
- **DirectoryScanner**: Efficient directory traversal and filtering
- **PathNormalizer**: Windows/Mac/Linux path compatibility
- **FileFilter**: Chainable filtering system
- **ProjectConfigManager**: Team configuration management with pacc.json schema validation

#### 2. UI Components (`pacc/ui/`)
- **MultiSelectList**: Interactive selection with keyboard navigation
- **SearchFilter**: Fuzzy and exact text matching
- **PreviewPane**: File and metadata preview
- **KeyboardHandler**: Cross-platform input handling

#### 3. Validation System (`pacc/validation/`)
- **BaseValidator**: Abstract foundation for all validators
- **FormatDetector**: Automatic file format detection
- **JSONValidator**: Complete JSON syntax validation
- **YAMLValidator**: YAML validation with optional PyYAML
- **MarkdownValidator**: Markdown structure validation

#### 4. Extension Validators (`pacc/validators/`)
- **HooksValidator**: JSON structure, event types, matchers, security scanning
- **MCPValidator**: Server configuration, executable checking, connection testing
- **AgentsValidator**: YAML frontmatter, tool validation, parameter schemas
- **CommandsValidator**: Markdown files, naming conventions, aliases

#### 5. Integration Layer (`pacc/selection/`, `pacc/packaging/`, `pacc/recovery/`, `pacc/performance/`)
- **Selection Workflow**: Interactive file selection with multiple strategies
- **Packaging Support**: Universal format conversion (ZIP, TAR, etc.)
- **Error Recovery**: Intelligent rollback with retry mechanisms
- **Performance Optimization**: Caching, lazy loading, background workers

#### 6. Memory Fragments (`pacc/fragments/`)
- **StorageManager**: Fragment storage with project/user level support
- **CLAUDEmdManager**: CLAUDE.md section management with atomic operations
- **InstallationManager**: Full installation workflow with rollback
- **VersionTracker**: Version tracking for updates from Git sources
- **SyncManager**: Team synchronization via pacc.json

#### 7. Error Handling (`pacc/errors/`)
- **Custom Exceptions**: Structured error types with context
- **ErrorReporter**: Centralized logging and user-friendly display
- **Security Features**: Path traversal protection, input sanitization

## Usage Examples

### Basic Validation
```python
from pacc.validators import ValidatorFactory

# Validate a hooks file
validator = ValidatorFactory.create_validator('hooks')
result = validator.validate('/path/to/hooks.json')

if result.is_valid:
    print("Validation passed!")
else:
    for error in result.errors:
        print(f"Error: {error.message}")
```

### Interactive Selection
```python
from pacc.selection import SelectionWorkflow

# Create interactive selection workflow
workflow = SelectionWorkflow()
selected_files = workflow.run_interactive_selection('/path/to/extensions/')
```

### Directory Scanning
```python
from pacc.core.file_utils import DirectoryScanner, FileFilter

# Scan directory for extension files
scanner = DirectoryScanner()
file_filter = FileFilter().by_extensions(['.json', '.md', '.yaml'])
files = scanner.scan('/path/to/directory', file_filter)
```

## Installation

### Quick Start

1. **Install from wheel** (recommended):
   ```bash
   pip install dist/pacc-1.1.0-py3-none-any.whl
   ```

2. **Verify installation**:
   ```bash
   pacc --version
   pacc --help
   ```

### Installation Options

#### Option 1: Wheel Installation (Production)
```bash
# Build the wheel
python scripts/build.py build --dist-type wheel

# Install the wheel
pip install dist/pacc-1.1.0-py3-none-any.whl
```

#### Option 2: Editable Installation (Development)
```bash
# Install in development mode
pip install -e .
```

#### Option 3: Build Everything
```bash
# Complete build and test workflow
python scripts/build.py build
python scripts/build.py check
python scripts/build.py test
```

### System Requirements

- **Python**: 3.8 or higher
- **Memory**: 50MB minimum
- **Storage**: 10MB for package
- **OS**: Windows, macOS, Linux

See [Package Installation Guide](docs/package_installation_guide.md) for detailed instructions.

## CLI Usage

PACC provides a complete package manager interface for Claude Code extensions:

### Installation
```bash
# Install from file or directory
pacc install /path/to/extension.json
pacc install /path/to/extension-directory/

# Install with options
pacc install extension.json --user --force
pacc install extensions/ --interactive --dry-run
```

### Listing Extensions
```bash
# List all installed extensions
pacc list

# Filter by type and scope
pacc list hooks --user
pacc list agents --project
pacc list --format json

# Search and filter
pacc list --search "code" --sort date
pacc list --filter "*-server" --format table
```

### Removing Extensions
```bash
# Remove extension safely
pacc remove my-hook

# Remove with options
pacc remove extension-name --user --dry-run
pacc remove extension-name --force --confirm
```

### Extension Information
```bash
# Show extension details
pacc info extension-name
pacc info /path/to/extension.json

# Detailed information with troubleshooting
pacc info extension-name --verbose --show-usage
pacc info extension-name --json --show-related
```

### Validation
```bash
# Validate extensions
pacc validate /path/to/extension.json
pacc validate extensions-directory/ --strict
```

## Development

### Prerequisites
- Python 3.8+
- uv (for dependency management)

### Setup
```bash
# Install dependencies
uv pip install -e .

# Run tests
uv run pytest

# Run type checking (if mypy is added)
uv run mypy pacc

# Run linting (if ruff is added)
uv run ruff check .
uv run ruff format .
```

### Testing
The project includes comprehensive testing:
- **Unit Tests**: 100+ test methods covering all components
- **Integration Tests**: Real-world workflows and multi-component interactions
- **E2E Tests**: Complete user journeys and cross-platform compatibility
- **Performance Tests**: Benchmarks for large-scale operations
- **Security Tests**: Protection against common vulnerabilities

### Performance Benchmarks
- **File Scanning**: >4,000 files/second
- **Validation**: >200 validations/second
- **Memory Usage**: <100MB for processing thousands of files
- **Cross-Platform**: Windows, Unix, Unicode support

## Security Features
- **Path Traversal Protection**: Prevents `../` attacks
- **Input Sanitization**: Blocks malicious patterns
- **Security Auditing**: File and directory security analysis
- **Policy Enforcement**: Configurable security levels

## Extension Types Supported

### 1. Hooks
- JSON structure validation
- Event type checking (PreToolUse, PostToolUse, Notification, Stop)
- Matcher validation (regex, glob patterns)
- Security analysis for command injection

### 2. MCP Servers
- Server configuration validation
- Executable path verification
- Environment variable validation
- Optional connection testing

### 3. Agents
- YAML frontmatter parsing
- Required field validation
- Tool and permission validation
- Parameter schema validation

### 4. Commands
- Markdown file validation
- Naming convention enforcement
- Parameter documentation checking
- Alias validation and duplicate detection

### 5. Memory Fragments
- Markdown with optional YAML frontmatter
- Automatic CLAUDE.md integration
- Version tracking for Git sources
- Collection organization support
- Team synchronization via pacc.json

## Next Steps
1. **CLI Integration**: Connect existing components to command-line interface
2. **JSON Configuration**: Implement settings.json merge strategies
3. **Final Testing**: End-to-end CLI workflow validation

## Contributing
This project follows standard Python development practices:
- Type hints throughout
- Comprehensive error handling
- Cross-platform compatibility
- Security-first design
- Extensive testing

## License
[License information to be added]