feat: add stacks, doctor, export commands + GitHub Pages site (v1.2.0)

[memyselfandm]

Close competitive gaps vs MCS-CLI by adding key "Ansible for Claude Code"
primitives:

• Stack management: install/list/remove/sync/export bundled environments
  (MCP servers + hooks + commands + agents + settings + fragments in one
  stack.yaml manifest)
• Doctor diagnostics: 12 health checks with auto-fix capability
• Export command: generate shareable stacks from existing config
• Lockfile support: pacc.lock.yaml with pinned git commits + SHA-256
• GitHub Pages marketing site with professional dark-theme design
• README revamp: "Ansible for Claude Code" positioning front and center
• Version bump to 1.2.0

https://claude.ai/code/session_0181hCPUwUmKnYoo69GEEGgB

[claude]

Claude finished @memyselfandm's task —— View job

---

Code Review Completed

Reviewing this substantial PR that introduces stack management, doctor diagnostics, and export functionality.

Todo List:

• Read repository guidelines (CLAUDE.md)
• Review GitHub Pages workflow and site implementation
• Analyze README changes and positioning updates
• Review CLI changes and new command structure
• Examine doctor.py implementation for diagnostics
• Review stacks module architecture and implementation
• Assess security considerations for new features
• Evaluate test coverage and missing tests
• Provide comprehensive feedback summary

---

🔍 Code Review Summary

This PR adds significant new functionality to close competitive gaps with MCS-CLI. Overall, the implementation is well-structured and follows the repository's established patterns, but there are several areas that need attention:

✅ Strengths

1. GitHub Pages Implementation

• Clean workflow: .github/workflows/pages.yml follows GitHub Pages best practices
• Professional site: docs/index.html is well-designed with proper SEO meta tags
• Responsive design: Good mobile support and accessibility considerations

2. Stack Management Architecture

• Well-designed data structures: StackManifest class with proper validation
• Idempotent operations: Safe sync functionality with proper error handling
• Lockfile support: pacc.lock.yaml with SHA-256 verification for reproducibility

3. Doctor Diagnostics System

• Comprehensive checks: 12 different health checks covering the entire environment
• Auto-fix capability: Smart remediation for common issues
• Clear reporting: Structured output with actionable feedback

4. CLI Integration

• Consistent patterns: New commands follow existing CLI conventions
• Proper error handling: Good use of try/catch and user feedback

⚠️ Issues & Concerns

1. Missing Test Coverage (Critical)

• No tests for new features: No test_stack_*.py or test_doctor.py files found
• Breaking change: This violates the repository's ">80% test coverage" requirement stated in CLAUDE.md
• Risk: New features could break without detection

Recommendation: Add comprehensive tests before merging:

# Required test files:
tests/unit/test_stack_manager.py
tests/unit/test_doctor.py  
tests/integration/test_stack_integration.py
tests/e2e/test_doctor_workflows.py

2. Security Concerns (High Priority)

Subprocess Command Injection Risk:
Multiple locations execute git commands with user input:

• stacks/manager.py:_clone_stack() - Line ~380
• doctor.py:check_git_dependencies() - Line ~450+
• cli.py:handle_stack_* methods

Example vulnerable pattern:

# stacks/manager.py line ~380
subprocess.run(
    ["git", "clone", "--depth", "1", source, str(tmp)], # source is user input
    capture_output=True,
    text=True,
    timeout=300,
)

Fix: Validate Git URLs and sanitize inputs:

def _validate_git_url(url: str) -> bool:
    """Validate git URL to prevent injection attacks."""
    import re
    pattern = r'^https://github\.com/[\w\-\.]+/[\w\-\.]+/?(?:\.git)?$'
    return bool(re.match(pattern, url))

3. YAML Dependency Management

• Optional dependency: PyYAML handling is inconsistent
• Runtime failures: Could fail unexpectedly if PyYAML not installed
• Better approach: Make PyYAML a required dependency in setup.py or provide better fallback

4. Resource Cleanup

• Temporary directories: Some git clone operations may leave temp files
• Stack management: Need cleanup validation in remove operations

5. Error Handling Improvements

• Git timeouts: Some git operations lack timeout handling
• Network failures: Limited retry logic for remote operations

🚀 Performance Considerations

1. Git Operations

• Concurrent cloning: Multiple stack installs could be parallelized
• Shallow clones: Good use of --depth 1 for performance

2. Doctor Checks

• Sequential execution: Could parallelize independent health checks
• Caching: Repeated checks could benefit from result caching

📋 Recommendations

Immediate (Before Merge):

1. Add comprehensive test coverage for stacks and doctor modules
2. Fix security vulnerabilities in git command execution
3. Make PyYAML a required dependency or improve fallback handling

Near-term (Next PR):

1. Parallelize doctor checks for better performance
2. Add retry logic for network operations
3. Improve error messages with actionable guidance

Architecture:

The overall design follows repository patterns well. The stack system is a solid foundation for the "Ansible for Claude Code" positioning, and the doctor system provides valuable operational capabilities.

📊 Files Changed Assessment

File	Quality	Concerns
docs/index.html	✅ Excellent	None
.github/workflows/pages.yml	✅ Good	None
README.md	✅ Good	None
cli.py	⚠️ Good	Missing input validation
doctor.py	⚠️ Good	No tests, git security
stacks/manager.py	⚠️ Good	No tests, command injection risk

🎯 Verdict

Conditional Approval - This PR significantly enhances PACC's capabilities, but critical test coverage and security issues must be addressed before merging. The architecture is sound and aligns well with the "Ansible for Claude Code" vision.