pacc-cli 1.1.0

Package manager for Claude Code - simplify installation and management of Claude Code extensions

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

# 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 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

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

from pacc.selection import SelectionWorkflow

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

Directory Scanning

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):

   pip install dist/pacc-1.1.0-py3-none-any.whl
   

2. Verify installation:

   pacc --version
   pacc --help
   

Installation Options

Option 1: Wheel Installation (Production)

# 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)

# Install in development mode
pip install -e .

Option 3: Build Everything

# 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 for detailed instructions.

CLI Usage

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

Installation

# 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

# 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

# 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

# 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

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

Development

Prerequisites

• Python 3.8+
• uv (for dependency management)

Setup

# 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]