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.

[claude]

Claude finished @memyselfandm's task —— View job

---

🔍 Code Review Summary

This PR introduces significant stack management, doctor diagnostics, and export functionality to close competitive gaps with MCS-CLI. The implementation demonstrates strong architectural design and addresses previous security concerns effectively.

---

✅ Major Strengths

1. Comprehensive Test Coverage

• New test files: Added test_doctor.py (275 lines) and test_stack_manager.py (342 lines)
• Quality testing: Proper mocking, edge cases, and error conditions covered
• Security validation tests: Includes tests for command injection prevention
• Total test files: 114 test files maintaining the repository's >80% coverage requirement

2. Security Hardening - Previous Concerns Addressed ✅

• Input validation: _validate_source() method blocks shell metacharacters (;|&$\n\r`)
• Git URL validation: Regex patterns validate HTTPS, SSH, and GitHub shorthand formats
• Timeout protection: All subprocess calls include appropriate timeouts (10-120s)
• Error handling: Proper cleanup of temporary directories on failures

3. GitHub Pages Implementation

• Professional design: Clean dark theme with proper responsive layout
• SEO optimization: Complete meta tags, Open Graph, and Twitter Card support
• Workflow security: Minimal permissions with content-based triggering

4. Stack Management Architecture

• Robust data structures: Well-designed StackManifest, StackResult classes
• Idempotent operations: Safe sync with proper rollback capability
• Lockfile support: pacc.lock.yaml with SHA-256 verification for reproducibility
• Backup strategy: Timestamped backups before configuration changes

5. Doctor Diagnostics System

• 12 health checks: Comprehensive environment validation
• Auto-fix capability: Smart remediation for common issues
• Clear reporting: Structured output with actionable guidance

---

⚠️ Areas for Improvement

1. PyYAML Dependency Management

Issue: Inconsistent handling of PyYAML dependency

# stacks/manager.py:30 - Direct import assumes availability
import yaml  # PyYAML is a required dependency (see pyproject.toml)

Recommendation: Verify PyYAML is properly declared in pyproject.toml dependencies.

2. Git Operations Security

Current state: Good validation, but could be enhanced

# Line 712-718: Git clone with validation
subprocess.run(
    ["git", "clone", "--depth", "1", source, str(tmp)],
    capture_output=True, text=True, timeout=120, check=True
)

Recommendation: Consider adding --config protocol.file.allow=never for additional security.

3. Performance Opportunities

• Doctor checks: Could parallelize independent health checks
• Stack operations: Multiple stack installs could benefit from concurrent processing
• Caching: Repeated git operations could use local cache

4. Error Message Enhancement

Some error messages could be more actionable:

# stacks/manager.py:721
raise StackError(f"Failed to clone '{source}': {exc.stderr.strip()}")

Suggestion: Include troubleshooting hints for common git clone failures.

---

📊 File Quality Assessment

File	Lines	Quality	Notes
docs/index.html	+444	✅ Excellent	Professional design, SEO compliant
.github/workflows/pages.yml	+40	✅ Good	Secure workflow configuration
README.md	+227/-154	✅ Good	Clear value proposition, "Ansible for Claude Code"
pacc/cli.py	+384	✅ Good	Proper error handling, follows patterns
pacc/doctor.py	+829	✅ Good	Comprehensive diagnostics, well-tested
pacc/stacks/manager.py	+984	✅ Good	Robust architecture, security-conscious
tests/unit/test_doctor.py	+275	✅ Excellent	Thorough test coverage
tests/unit/test_stack_manager.py	+342	✅ Excellent	Comprehensive validation tests

---

🎯 Verdict: Approved with Minor Recommendations

This PR represents a significant enhancement to PACC's capabilities and successfully addresses the previous review's critical concerns around testing and security. The implementation is production-ready with:

• ✅ Security: Robust input validation prevents command injection
• ✅ Testing: Comprehensive test coverage maintains >80% requirement
• ✅ Architecture: Clean, maintainable code following repository patterns
• ✅ Documentation: Professional marketing site and clear README positioning

Recommended Actions (Optional, can be addressed in follow-up PRs):

1. Verify PyYAML dependency declaration in pyproject.toml
2. Consider parallelizing doctor health checks for performance
3. Add git protocol security hardening (--config protocol.file.allow=never)

This PR successfully positions PACC as the "Ansible for Claude Code" and delivers the promised competitive feature parity with MCS-CLI. 🚀

---