mcp-souschef 2.0.1__tar.gz → 2.2.0__tar.gz

{mcp_souschef-2.0.1 → mcp_souschef-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-souschef
-Version: 2.0.1
+Version: 2.2.0
 Summary: AI-powered MCP server for Chef to Ansible conversion
 License: MIT
 License-File: LICENSE
@@ -16,12 +16,12 @@ Requires-Dist: python-dotenv (>=1.2.1)
 Requires-Dist: zod (>=0.8.0)
 Description-Content-Type: text/markdown
 
-# Chef to Ansible migration - SousChef MCP 🍳
+# Chef to Ansible migration - SousChef MCP
 
 An AI-powered MCP (Model Context Protocol) server that provides comprehensive Chef-to-Ansible migration capabilities for enterprise infrastructure transformation.
 
 [![PyPI version](https://img.shields.io/pypi/v/mcp-souschef.svg)](https://pypi.org/project/mcp-souschef/)
-[![Python Version](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
+[![Python Version](https://img.shields.io/badge/python-3.14%2B-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Test Coverage](https://img.shields.io/badge/coverage-92%25-brightgreen.svg)](htmlcov/index.html)
 [![Code style: Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
@@ -32,9 +32,24 @@ An AI-powered MCP (Model Context Protocol) server that provides comprehensive Ch
 
 ## Overview - Chef to Ansible features
 
-SousChef is a complete enterprise-grade migration platform with 34 MCP tools organized across 8 major capability areas to facilitate Chef-to-Ansible AWX/AAP migrations. From cookbook analysis to deployment pattern conversion, SousChef provides everything needed for a successful infrastructure automation migration.
+SousChef is a complete enterprise-grade migration platform with 38 MCP tools organized across 9 major capability areas to facilitate Chef-to-Ansible AWX/AAP migrations. From cookbook analysis to deployment pattern conversion, including Chef Habitat to containerized deployments, SousChef provides everything needed for a successful infrastructure automation migration.
 
-## 📦 Installation
+## Model Agnostic - Works with Any AI Model
+
+**SousChef works with ANY AI model through the Model Context Protocol (MCP)**. The MCP architecture separates tools from models:
+
+- **Red Hat AI** (Llama, IBM models)
+- **Claude** (Anthropic)
+- **GPT-4/GPT-3.5** (OpenAI)
+- **GitHub Copilot** (Microsoft/OpenAI)
+- **Local Models** (Ollama, llama.cpp, etc.)
+- **Custom Enterprise Models**
+
+**How it works:** You choose your AI model provider in your MCP client. SousChef provides the Chef/Ansible expertise through 38 specialized tools. The model calls these tools to help with your migration.
+
+> See [config/CONFIGURATION.md](config/CONFIGURATION.md) for configuration examples with different model providers.
+
+## Installation
 
 ```bash
 # PyPI Installation
@@ -46,9 +61,9 @@ cd souschef
 poetry install
 ```
 
-> **📖 For detailed installation instructions, MCP setup, and configuration, see [Installation & Setup](#installation--setup)**
+> **For detailed installation instructions, MCP setup, and configuration, see [Installation & Setup](#installation--setup)**
 
-## 🚀 Core Capabilities
+## Core Capabilities
 
 ### 1. Chef Cookbook Analysis & Parsing
 Complete cookbook introspection and analysis tools:
@@ -59,7 +74,7 @@ Complete cookbook introspection and analysis tools:
 - **read_file** - Read cookbook files with error handling
 - **read_cookbook_metadata** - Parse metadata.rb files for dependencies and cookbook information
 - **parse_recipe** - Analyze Chef recipes and extract resources, actions, and properties
-- **parse_attributes** - Parse attribute files (default, override, normal) with precedence analysis
+- **parse_attributes** - Parse attribute files with **advanced precedence resolution** (6 levels: default, force_default, normal, override, force_override, automatic)
 - **list_cookbook_structure** - Display complete cookbook directory hierarchy
 
 ### 2. Chef-to-Ansible Conversion Engine
@@ -67,6 +82,12 @@ Advanced resource-to-task conversion with intelligent module selection:
 
 - **convert_resource_to_task** - Transform individual Chef resources to Ansible tasks
 - **generate_playbook_from_recipe** - Generate complete Ansible playbooks from Chef recipes
+- **Enhanced Guard Handling** - Convert complex Chef guards to Ansible when/unless conditions
+  - Array-based guards: `only_if ['condition1', 'condition2']`
+  - Lambda/proc syntax: `only_if { ::File.exist?('/path') }`
+  - Do-end blocks: `not_if do ... end`
+  - Multiple guard types per resource with proper AND/OR logic
+  - Platform checks, node attributes, file/directory existence, and command execution
 
 ### 3. Chef Search & Inventory Integration
 Convert Chef search patterns to dynamic Ansible inventory:
@@ -104,19 +125,69 @@ Enterprise AWX/AAP configuration generation:
 - **generate_awx_project_from_cookbooks** - Generate AWX projects from cookbook collections
 - **generate_awx_inventory_source_from_chef** - Create dynamic inventory sources from Chef server
 
-### 8. Advanced Deployment Patterns & Migration Assessment
+### 8. Chef Habitat to Container Conversion
+Modernize Habitat applications to containerized deployments:
+
+- **parse_habitat_plan** - Parse Chef Habitat plan files (plan.sh) and extract package metadata, dependencies, build/install hooks, and service configuration
+- **convert_habitat_to_dockerfile** - Convert Chef Habitat plans to production-ready Dockerfiles with security validation
+- **generate_compose_from_habitat** - Generate docker-compose.yml from multiple Habitat plans for multi-service deployments
+
+### 9. Advanced Deployment Patterns & Migration Assessment
 Modern deployment strategies and migration planning:
 
 - **convert_chef_deployment_to_ansible_strategy** - Convert deployment recipes to Ansible strategies
 - **generate_blue_green_deployment_playbook** - Create blue/green deployment playbooks
 - **generate_canary_deployment_strategy** - Generate canary deployment configurations
+
+### 10. Conversion Validation Framework
+Comprehensive validation of Chef-to-Ansible conversions:
+
+- **validate_conversion** - Validate conversions across multiple dimensions
+  - **Syntax Validation**: YAML, Jinja2, Python syntax checking
+  - **Semantic Validation**: Logic equivalence, variable usage, resource dependencies
+  - **Best Practice Checks**: Naming conventions, idempotency, task organization
+  - **Security Validation**: Privilege escalation patterns, sensitive data handling
+  - **Performance Recommendations**: Efficiency suggestions and optimizations
+
+#### Validation Levels
+- **ERROR**: Critical issues that will prevent execution
+- **WARNING**: Potential problems or anti-patterns that may cause issues
+- **INFO**: Suggestions for improvements and best practices
+
+#### Validation Categories
+- **Syntax**: Code structure and syntax correctness
+- **Semantic**: Logical equivalence and meaning preservation
+- **Best Practice**: Ansible community standards and patterns
+- **Security**: Security considerations and recommendations
+- **Performance**: Efficiency and optimization suggestions
+
+#### Example Usage
+
+```python
+# Validate a resource conversion
+validate_conversion(
+    conversion_type="resource",
+    result_content="""- name: Install nginx
+  ansible.builtin.package:
+    name: "nginx"
+    state: present
+""",
+    output_format="text"  # Options: text, json, summary
+)
+```
+
+Output formats:
+- **text**: Detailed report with all findings grouped by severity
+- **json**: Structured JSON for programmatic processing
+- **summary**: Quick overview with counts only
+
 - **analyze_chef_application_patterns** - Identify application deployment patterns
 - **assess_chef_migration_complexity** - Comprehensive migration complexity assessment
 - **generate_migration_plan** - Create detailed migration execution plans
 - **analyze_cookbook_dependencies** - Analyze dependencies and migration order
 - **generate_migration_report** - Generate executive and technical migration reports
 
-## 🎯 Migration Workflow
+## Migration Workflow
 
 ### Phase 1: Discovery & Assessment
 ```bash
@@ -154,7 +225,19 @@ generate_awx_workflow_from_chef_runlist \"recipe[app::deploy]\" workflow_name
 generate_awx_inventory_source_from_chef https://chef.example.com production web_servers
 ```
 
-### Phase 4: Validation & Testing
+### Phase 4: Habitat to Container Migration
+```bash
+# Parse Habitat plan
+parse_habitat_plan /path/to/plan.sh
+
+# Convert to Dockerfile
+convert_habitat_to_dockerfile /path/to/plan.sh ubuntu:22.04
+
+# Generate docker-compose for multiple services
+generate_compose_from_habitat "/path/to/plan1.sh,/path/to/plan2.sh" my_network
+```
+
+### Phase 5: Validation & Testing
 ```bash
 # Generate InSpec validation
 generate_inspec_from_recipe /path/to/recipe.rb
@@ -163,7 +246,34 @@ generate_inspec_from_recipe /path/to/recipe.rb
 convert_inspec_to_test /path/to/inspec_profile testinfra
 ```
 
-## 📊 Enterprise Features
+### Performance Profiling & Optimization
+Profile cookbook parsing performance to identify bottlenecks and optimize large-scale migrations:
+
+```bash
+# Profile entire cookbook (all parsing operations)
+souschef-cli profile /path/to/cookbook
+
+# Save profiling report to file
+souschef-cli profile /path/to/cookbook --output profile_report.txt
+
+# Profile specific operations with detailed statistics
+souschef-cli profile-operation recipe /path/to/recipe.rb --detailed
+souschef-cli profile-operation attributes /path/to/attributes/default.rb
+souschef-cli profile-operation template /path/to/template.erb
+
+# MCP Tool Usage (from AI assistants)
+profile_cookbook_performance /path/to/large_cookbook
+profile_parsing_operation recipe /path/to/recipe.rb --detailed
+```
+
+**Features:**
+-  Execution time and peak memory tracking for all parsing operations
+-  Detailed cProfile statistics with top function calls
+-  Automatic performance recommendations based on thresholds
+-  Before/after comparison for optimization validation
+-  Integration with CLI and MCP for AI-assisted profiling
+
+## Enterprise Features
 
 ### Migration Assessment & Reporting
 - **Complexity Analysis**: Automated assessment of migration effort and risk factors
@@ -176,6 +286,7 @@ convert_inspec_to_test /path/to/inspec_profile testinfra
 - **Canary Releases**: Gradual rollout configurations
 - **Application Patterns**: Modern containerized and cloud-native deployment patterns
 - **Rollback Strategies**: Automated failure recovery procedures
+- **Habitat to Container**: Convert Chef Habitat plans to Docker and Docker Compose configurations
 
 ### Enterprise Integration
 - **AWX/AAP Ready**: Native Ansible Automation Platform integration
@@ -183,7 +294,7 @@ convert_inspec_to_test /path/to/inspec_profile testinfra
 - **Secrets Management**: Secure data bag to Vault conversion
 - **Multi-Environment**: Production-ready inventory and variable management
 
-## 🛠️ Installation & Setup
+## Installation & Setup
 
 ### Prerequisites
 - Python 3.14+
@@ -197,23 +308,25 @@ convert_inspec_to_test /path/to/inspec_profile testinfra
    pip install mcp-souschef
    ```
 
-2. **Configure MCP Client**:
+2. **Configure Your MCP Client**:
+
+   Use the pre-configured files in the `config/` directory for quick setup with Claude Desktop, VS Code Copilot, or other MCP clients.
 
-   **🎯 Quick Setup - Use Pre-configured Files:**
    ```bash
-   # Claude Desktop (macOS)
+   # Example: Claude Desktop (macOS)
    cp config/claude-desktop.json ~/Library/Application\ Support/Claude/claude_desktop_config.json
-
-   # VS Code Copilot (macOS/Linux)
-   mkdir -p ~/.config/Code/User/globalStorage/github.copilot-chat
-   cp config/vscode-copilot.json ~/.config/Code/User/globalStorage/github.copilot-chat/mcp.json
    ```
 
-   See [config/README.md](config/README.md) for detailed setup instructions, development configs, and troubleshooting.
+   ** See [config/CONFIGURATION.md](config/CONFIGURATION.md) for:**
+   - Platform-specific setup (macOS/Linux/Windows)
+   - Model provider configurations (Red Hat AI, OpenAI, local models)
+   - Development setup
+   - Troubleshooting
 
-3. **Start using SousChef**:
-   - **Claude Desktop**: Restart Claude, then ask: "What tools does souschef provide?"
-   - **VS Code Copilot**: Reload window, then use: `@souschef analyze this cookbook`
+3. **Start Using SousChef**:
+   - Restart your MCP client
+   - Ask: "What Chef migration tools are available?"
+   - Begin analyzing your cookbooks!
 
 ### Command Line Interface (CLI)
 
@@ -288,28 +401,31 @@ poetry update              # All packages
 ```
 
 **Automated Systems:**
-- ✅ Pre-commit hooks auto-update `poetry.lock` when `pyproject.toml` changes
-- ✅ CI validates lock file on every PR
-- ✅ Dependabot sends weekly dependency updates
+-  Pre-commit hooks auto-update `poetry.lock` when `pyproject.toml` changes
+-  CI validates lock file on every PR
+-  Dependabot sends weekly dependency updates
 
 See [CONTRIBUTING.md](CONTRIBUTING.md#-managing-dependencies) for detailed dependency management guide.
 
-## 🏗️ Architecture & Design
+## Architecture & Design
 
 ### MCP Protocol Integration
 SousChef leverages the Model Context Protocol (MCP) to provide seamless integration with AI assistants and development environments:
 
-- **34 Specialized Tools**: Each migration capability exposed as dedicated MCP tool
+- **38 Specialized Tools**: Each migration capability exposed as dedicated MCP tool
 - **Type-Safe Interfaces**: Full Python type hints for reliable AI interactions
 - **Comprehensive Error Handling**: Graceful degradation and helpful error messages
 - **Streaming Support**: Efficient handling of large cookbook conversions
 
 ### Testing Strategy
-Following enterprise-grade testing standards:
-
-- **Unit Tests**: Mock-based testing for individual functions (tests/test_server.py)
-- **Integration Tests**: Real cookbook testing with fixtures (tests/test_integration.py)
-- **Property-Based Tests**: Hypothesis fuzz testing for edge cases (tests/test_property_based.py)
+Following enterprise-grade testing standards with comprehensive test coverage:
+
+- **Unit Tests**: Mock-based testing for individual functions (test_server.py, test_cli.py, test_mcp.py)
+- **Integration Tests**: Real cookbook testing with fixtures (test_integration.py, test_integration_accuracy.py)
+- **Property-Based Tests**: Hypothesis fuzz testing for edge cases (test_property_based.py)
+- **Specialized Tests**: Enhanced guards (test_enhanced_guards.py), error handling (test_error_paths.py, test_error_recovery.py), real-world fixtures (test_real_world_fixtures.py)
+- **Performance Tests**: Benchmarking and optimization validation (test_performance.py)
+- **Snapshot Tests**: Regression testing for output stability (test_snapshots.py)
 - **92% Coverage**: Comprehensive test coverage exceeding the 90% target for production readiness
 
 ### Quality Assurance
@@ -318,7 +434,7 @@ Following enterprise-grade testing standards:
 - **Automated Testing**: CI/CD pipeline with comprehensive test suites
 - **Documentation**: Detailed docstrings and usage examples
 
-## 📚 Documentation
+## Documentation
 
 ### Tool Reference
 Each MCP tool includes comprehensive documentation:
@@ -346,36 +462,39 @@ We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for:
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
-## 🚀 Roadmap
+## Roadmap
 
 ### Completed ✅
-- ✅ Complete Chef cookbook parsing (recipes, attributes, metadata, templates)
-- ✅ InSpec profile parsing and conversion to Testinfra/Ansible tests
-- ✅ Chef resource to Ansible task conversion with module mapping
-- ✅ Data bags to Ansible Vault conversion
-- ✅ Chef environments to Ansible inventory conversion
-- ✅ Chef search patterns to dynamic inventory conversion
-- ✅ AWX/AAP job templates, workflows, and project generation
-- ✅ Blue/green and canary deployment pattern generation
-- ✅ Migration complexity assessment and planning tools
-- ✅ Comprehensive testing suite (unit, integration, property-based)
-- ✅ Command-line interface (CLI) for standalone usage
-
-### In Progress 🔄
-- 🔄 Enhanced error handling and user experience improvements
-- 🔄 Documentation website and interactive examples
-- 🔄 Performance optimizations for large-scale enterprise migrations
-- 🔄 Technical debt reduction (15 functions tracked in [GitHub Issues](https://github.com/kpeacocke/souschef/issues?q=is%3Aissue+is%3Aopen+label%3Atechnical-debt))
+-  Complete Chef cookbook parsing (recipes, attributes, metadata, templates)
+-  InSpec profile parsing and conversion to Testinfra/Ansible tests
+-  Chef resource to Ansible task conversion with module mapping
+-  Data bags to Ansible Vault conversion
+-  Chef environments to Ansible inventory conversion
+-  Chef search patterns to dynamic inventory conversion
+-  AWX/AAP job templates, workflows, and project generation
+-  Blue/green and canary deployment pattern generation
+-  Migration complexity assessment and planning tools
+-  Comprehensive testing suite (unit, integration, property-based)
+-  Command-line interface (CLI) for standalone usage
+-  Enhanced Chef guard handling (arrays, lambda syntax, complex nested conditions)
+-  Advanced attribute precedence resolution (6 levels with conflict detection)
+-  Automated release management with Release Please
+-  Automated branch cleanup for release PRs
+-  Automated conversion validation and testing framework
+-  Chef Habitat to containerized deployment conversion (parse_habitat_plan, convert_habitat_to_dockerfile, generate_compose_from_habitat)
+-  Enhanced error handling with custom exceptions and actionable recovery suggestions
+-  Technical debt reduction - ALL PHASES COMPLETE: 16 functions refactored (15 C-grade eliminated, 70+ helpers extracted, average 77% complexity reduction, zero C-grade functions remaining)
+-  Performance profiling and optimization for large cookbooks (profiling module, CLI commands, MCP tools)
+
+### In Progress 🚧
+-  Documentation website with MkDocs + Material theme
+-  Documentation content (Getting Started, Tool Reference, Migration Guide)
 
 ### Planned 📅
-- 📅 Chef Habitat to containerized deployment conversion
 - 📅 Integration with additional test frameworks (ServerSpec, Goss)
 - 📅 Visual migration planning and dependency mapping interface
 - 📅 Terraform provider for infrastructure state management
 - 📅 Jenkins/GitLab CI pipeline generation
-- 📅 Advanced Chef guard handling (only_if, not_if conditions)
-- 📅 Complex attribute precedence and merging logic
-- 📅 Conversion validation and testing framework
 
 ## 🙋‍♀️ Support & Community
 
@@ -385,7 +504,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ---
 
-**SousChef** - *Transforming infrastructure automation, one recipe at a time.* 🍳✨
+**SousChef** - *Transforming infrastructure automation, one recipe at a time.* ✨
   desc 'Ensure package nginx is properly configured'
   impact 1.0
 
@@ -554,17 +673,59 @@ parse_recipe("/path/to/cookbook/recipes/default.rb")
 #   Action: install
 ```
 
-#### `parse_attributes(path: str)`
-Parse a Chef attributes file and extract attribute definitions.
+#### `parse_attributes(path: str, resolve_precedence: bool = True)`
+Parse a Chef attributes file and extract attribute definitions with precedence analysis.
+
+**Chef Attribute Precedence** (lowest to highest):
+1. `default` - Normal default value
+2. `force_default` - Forced default, higher than regular default
+3. `normal` - Normal attribute set by cookbook
+4. `override` - Override values
+5. `force_override` - Forced override, cannot be overridden
+6. `automatic` - Automatically detected by Ohai (highest precedence)
+
+When multiple attributes with the same path exist at different precedence levels, the highest precedence wins. The tool automatically resolves conflicts and reports which values were overridden.
+
+**Parameters:**
+- `path`: Path to the attributes (.rb) file
+- `resolve_precedence`: If True (default), resolves conflicts and shows only winning values. If False, shows all attributes.
 
 **Example:**
 ```python
+# With precedence resolution (default)
 parse_attributes("/path/to/cookbook/attributes/default.rb")
 # Returns:
+# Resolved Attributes (with precedence):
+# ==================================================
+#
+# Attribute: nginx.port
+#   Value: 443
+#   Precedence: force_override (level 5)
+#     Overridden values: default=80, normal=8080
+#
+# Attribute: nginx.ssl_port
+#   Value: 443
+#   Precedence: default (level 1)
+#
+# ==================================================
+# Total attributes: 2
+# Attributes with precedence conflicts: 1
+
+# Without precedence resolution (show all)
+parse_attributes("/path/to/cookbook/attributes/default.rb", resolve_precedence=False)
+# Returns:
 # default[nginx.port] = 80
+# normal[nginx.port] = 8080
+# force_override[nginx.port] = 443
 # default[nginx.ssl_port] = 443
 ```
 
+**Use Cases:**
+- Understanding attribute conflicts in complex cookbooks
+- Debugging which attributes will actually be applied
+- Planning attribute migrations to Ansible variables
+- Identifying force_override attributes that need special handling
+
 #### `list_cookbook_structure(path: str)`
 List the structure of a Chef cookbook directory.
 
@@ -700,6 +861,207 @@ convert_resource_to_task("template", "/etc/nginx/nginx.conf.erb", "create")
 - `group` → `ansible.builtin.group`
 - And more...
 
+#### `parse_habitat_plan(plan_path: str)`
+Parse a Chef Habitat plan file (plan.sh) and extract package metadata, dependencies, build/install hooks, and service configuration.
+
+**Example:**
+```python
+parse_habitat_plan("/path/to/habitat/plan.sh")
+# Returns JSON with:
+# {
+#   "package": {
+#     "name": "nginx",
+#     "origin": "core",
+#     "version": "1.25.3",
+#     "maintainer": "The Habitat Maintainers",
+#     "description": "High-performance HTTP server"
+#   },
+#   "dependencies": {
+#     "build": ["core/gcc", "core/make"],
+#     "runtime": ["core/glibc", "core/openssl"]
+#   },
+#   "ports": [
+#     {"name": "http", "value": "http.port"},
+#     {"name": "https", "value": "http.ssl_port"}
+#   ],
+#   "binds": [
+#     {"name": "database", "value": "postgresql.default"}
+#   ],
+#   "service": {
+#     "run": "nginx -g 'daemon off;'",
+#     "user": "nginx"
+#   },
+#   "callbacks": {
+#     "do_build": "./configure --prefix=/usr/local\nmake",
+#     "do_install": "make install",
+#     "do_init": "mkdir -p /var/lib/nginx"
+#   }
+# }
+```
+
+**Extracted Information:**
+- **Package metadata**: name, origin, version, maintainer, description
+- **Dependencies**: Build-time and runtime package dependencies
+- **Ports**: Exported port configurations for service discovery
+- **Binds**: Service bindings to other Habitat services
+- **Service configuration**: Run command, user, and initialization scripts
+- **Build callbacks**: do_build, do_install, do_init, and other lifecycle hooks
+
+**Use Cases:**
+- Understanding Habitat application structure before containerization
+- Extracting dependencies for Docker base image selection
+- Planning port mappings for docker-compose configurations
+- Analyzing service dependencies and orchestration needs
+
+#### `convert_habitat_to_dockerfile(plan_path: str, base_image: str = "ubuntu:22.04")`
+Convert a Chef Habitat plan to a production-ready Dockerfile with security validation.
+
+**Example:**
+```python
+convert_habitat_to_dockerfile("/path/to/habitat/plan.sh", "ubuntu:22.04")
+# Returns:
+# # Dockerfile generated from Habitat plan
+# # Original plan: plan.sh
+# # Package: core/nginx
+# # Version: 1.25.3
+#
+# FROM ubuntu:22.04
+#
+# LABEL maintainer="The Habitat Maintainers"
+# LABEL version="1.25.3"
+#
+# # Install dependencies
+# RUN apt-get update && apt-get install -y --no-install-recommends \
+#     gcc \
+#     make \
+#     libssl-dev \
+#     && rm -rf /var/lib/apt/lists/*
+#
+# # Build steps
+# WORKDIR /usr/local/src
+# RUN ./configure --prefix=/usr/local && \
+#     make
+#
+# # Install steps
+# RUN make install
+#
+# # Initialization steps
+# RUN mkdir -p /var/lib/nginx
+#
+# # Runtime configuration
+# EXPOSE 80
+# EXPOSE 443
+# USER nginx
+# WORKDIR /usr/local
+#
+# CMD ["nginx", "-g", "daemon off;"]
+```
+
+**Parameters:**
+- `plan_path`: Path to the Habitat plan.sh file
+- `base_image`: Docker base image (default: ubuntu:22.04). Validated for security
+
+**Features:**
+- **Dependency mapping**: Converts Habitat dependencies to apt packages
+- **Build optimization**: Multi-stage builds when applicable
+- **Security scanning**: Detects dangerous patterns (curl|sh, eval, etc.)
+- **Metadata preservation**: LABEL instructions for package info
+- **User configuration**: Non-root user setup when specified
+- **Port exposure**: Automatic EXPOSE directives from plan ports
+
+**Security Warnings:**
+The tool processes shell commands from Habitat plans and includes them in the Dockerfile. Only use with trusted Habitat plans from known sources. Review generated Dockerfiles before building images.
+
+#### `generate_compose_from_habitat(plan_paths: str, network_name: str = "habitat_net")`
+Generate docker-compose.yml from multiple Habitat plans for multi-service deployments.
+
+**Example:**
+```python
+# Single service
+generate_compose_from_habitat("/path/to/nginx/plan.sh", "myapp_network")
+# Returns:
+# version: '3.8'
+# services:
+#   nginx:
+#     build:
+#       context: .
+#       dockerfile: Dockerfile.nginx
+#     container_name: nginx
+#     ports:
+#       - "80:80"
+#       - "443:443"
+#     environment:
+#       - HTTP=80
+#       - HTTPS=443
+#     networks:
+#       - myapp_network
+#
+# networks:
+#   myapp_network:
+#     driver: bridge
+
+# Multiple services with dependencies
+generate_compose_from_habitat(
+    "/path/to/backend/plan.sh,/path/to/postgres/plan.sh",
+    "app_network"
+)
+# Returns:
+# version: '3.8'
+# services:
+#   backend:
+#     build:
+#       context: .
+#       dockerfile: Dockerfile.backend
+#     container_name: backend
+#     ports:
+#       - "8080:8080"
+#     environment:
+#       - PORT=8080
+#     depends_on:
+#       - postgres
+#     networks:
+#       - app_network
+#
+#   postgres:
+#     build:
+#       context: .
+#       dockerfile: Dockerfile.postgres
+#     container_name: postgres
+#     ports:
+#       - "5432:5432"
+#     environment:
+#       - POSTGRESQL=5432
+#     volumes:
+#       - postgres_data:/var/lib/app
+#     networks:
+#       - app_network
+#
+# networks:
+#   app_network:
+#     driver: bridge
+#
+# volumes:
+#   postgres_data:
+```
+
+**Parameters:**
+- `plan_paths`: Comma-separated paths to plan.sh files for multiple services
+- `network_name`: Docker network name for service communication (default: habitat_net)
+
+**Features:**
+- **Multi-service orchestration**: Combines multiple Habitat plans into one compose file
+- **Automatic dependencies**: Creates depends_on from Habitat service binds
+- **Volume detection**: Identifies services needing persistent storage from do_init callbacks
+- **Network isolation**: Configures bridge networks for service communication
+- **Port management**: Maps ports from Habitat exports to Docker compose
+- **Environment variables**: Generates environment configuration from port definitions
+
+**Use Cases:**
+- Converting multi-service Habitat applications to Docker Compose
+- Creating development environments from production Habitat plans
+- Simplifying container orchestration for local testing
+- Migration path from Habitat to Kubernetes (via docker-compose)
+
 ## Development
 
 ### Project Structure
@@ -760,14 +1122,19 @@ poetry run pytest
 # Run with coverage report
 poetry run pytest --cov=souschef --cov-report=term-missing --cov-report=html
 
-# Run only unit tests (mocked)
-poetry run pytest tests/test_server.py
-
-# Run only integration tests (real files)
-poetry run pytest tests/test_integration.py
-
-# Run property-based tests
-poetry run pytest tests/test_property_based.py
+# Run specific test suites
+poetry run pytest tests/test_server.py              # Core unit tests
+poetry run pytest tests/test_cli.py                 # CLI tests
+poetry run pytest tests/test_mcp.py                 # MCP protocol tests
+poetry run pytest tests/test_integration.py         # Integration tests
+poetry run pytest tests/test_integration_accuracy.py # Accuracy validation
+poetry run pytest tests/test_enhanced_guards.py     # Guard conversion tests
+poetry run pytest tests/test_error_paths.py         # Error handling
+poetry run pytest tests/test_error_recovery.py      # Error recovery
+poetry run pytest tests/test_real_world_fixtures.py # Real-world cookbooks
+poetry run pytest tests/test_property_based.py      # Hypothesis fuzz tests
+poetry run pytest tests/test_performance.py         # Performance benchmarks
+poetry run pytest tests/test_snapshots.py           # Snapshot regression tests
 
 # Run with benchmarks
 poetry run pytest --benchmark-only
@@ -780,28 +1147,37 @@ poetry run mypy souschef       # Type checking
 
 ### Test Types
 
-The project includes multiple types of tests:
+The project includes comprehensive test coverage across multiple dimensions:
 
-1. **Unit Tests** (`test_server.py`)
+1. **Unit Tests** (`test_server.py`, `test_cli.py`, `test_mcp.py`)
    - Mock-based tests for individual functions
    - Test error handling and edge cases
    - Fast execution, isolated from filesystem
+   - MCP protocol compliance testing
 
-2. **Integration Tests** (`test_integration.py`)
+2. **Integration Tests** (`test_integration.py`, `test_integration_accuracy.py`)
    - Real file operations with test fixtures
    - Validate parsing with actual Chef cookbook files
    - Parameterized tests for various scenarios
-   - Performance benchmarks with pytest-benchmark
+   - Accuracy validation for conversions
 
 3. **Property-Based Tests** (`test_property_based.py`)
    - Uses Hypothesis for fuzz testing
    - Generates random inputs to find edge cases
    - Ensures functions handle any input gracefully
 
-4. **Test Fixtures**
-   - Sample Chef cookbook in `tests/fixtures/sample_cookbook/`
-   - Real-world metadata, recipes, and attributes
-   - Used for integration testing
+4. **Specialized Test Suites**
+   - **Enhanced Guards** (`test_enhanced_guards.py`): Complex guard condition conversion
+   - **Error Handling** (`test_error_paths.py`, `test_error_recovery.py`): Comprehensive error scenarios
+   - **Real-World Fixtures** (`test_real_world_fixtures.py`): Production cookbook patterns
+   - **Performance** (`test_performance.py`): Benchmarking and optimization
+   - **Snapshots** (`test_snapshots.py`): Regression testing for output stability
+
+5. **Test Fixtures**
+   - Sample Chef cookbooks in `tests/fixtures/`
+   - Multiple cookbook types: apache2, docker, mysql, nodejs, legacy Chef 12, Habitat plans
+   - Real-world metadata, recipes, attributes, and resources
+   - Used across integration and accuracy testing
 
 ### Test Coverage
 
@@ -845,5 +1221,5 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ---
 
-**SousChef** - *Ansible automation, one recipe at a time.* 🍳✨
+**SousChef** - *Ansible automation, one recipe at a time.* ✨