{"id":35627366,"url":"https://github.com/kpeacocke/souschef","last_synced_at":"2026-02-15T22:14:45.287Z","repository":{"id":331976981,"uuid":"1126993229","full_name":"kpeacocke/souschef","owner":"kpeacocke","description":"Chef to Ansible converter for enterprise automation: migrate Chef cookbooks, recipes, and data bags (Vault), convert InSpec to Testinfra, generate Ansible playbooks/roles and AWX/AAP workflows via an AI-powered MCP server.","archived":false,"fork":false,"pushed_at":"2026-01-27T06:49:44.000Z","size":3325,"stargazers_count":1,"open_issues_count":47,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-27T08:32:47.438Z","etag":null,"topics":["aap","ai","ansible","ansible-automation-platform","ansible-web-executable","awx","chef","chef-to-ansible","cookbooks","devops","inspec","mcp","migration","testinfra"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kpeacocke.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-03T00:38:04.000Z","updated_at":"2026-01-27T00:53:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kpeacocke/souschef","commit_stats":null,"previous_names":["kpeacocke/souschef"],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/kpeacocke/souschef","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kpeacocke%2Fsouschef","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kpeacocke%2Fsouschef/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kpeacocke%2Fsouschef/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kpeacocke%2Fsouschef/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kpeacocke","download_url":"https://codeload.github.com/kpeacocke/souschef/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kpeacocke%2Fsouschef/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28828776,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-27T23:29:49.665Z","status":"ssl_error","status_checked_at":"2026-01-27T23:25:58.379Z","response_time":168,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aap","ai","ansible","ansible-automation-platform","ansible-web-executable","awx","chef","chef-to-ansible","cookbooks","devops","inspec","mcp","migration","testinfra"],"created_at":"2026-01-05T08:13:09.087Z","updated_at":"2026-02-15T22:14:45.277Z","avatar_url":"https://github.com/kpeacocke.png","language":"Python","readme":"# Chef to Ansible Migration \u0026 Ansible Upgrades - SousChef MCP\n\nAn AI-powered MCP (Model Context Protocol) server that provides comprehensive Chef-to-Ansible migration capabilities and Ansible upgrade planning for enterprise infrastructure transformation.\n\n[![GitHub release](https://img.shields.io/github/v/release/kpeacocke/souschef)](https://github.com/kpeacocke/souschef/releases)\n[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Test Coverage](https://img.shields.io/badge/coverage-91%25-green.svg)](htmlcov/index.html)\n[![Code style: Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)\n[![Type Checked: mypy](https://img.shields.io/badge/type%20checked-mypy-blue.svg)](http://mypy-lang.org/)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=kpeacocke_souschef\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=kpeacocke_souschef)\n[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=kpeacocke_souschef\u0026metric=security_rating)](https://sonarcloud.io/summary/new_code?id=kpeacocke_souschef)\n[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=kpeacocke_souschef\u0026metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=kpeacocke_souschef)\n\n## Overview\n\nSousChef is a complete enterprise-grade platform with two major capabilities:\n\n### 1. Chef to Ansible Migration (38 tools)\n\nComplete enterprise-grade migration platform with **38 primary MCP tools** organised across **9 major capability areas** to facilitate Chef-to-Ansible AWX/AAP migrations. From cookbook analysis to deployment pattern conversion, including Chef Habitat to containerised deployments, Chef Server integration, CI/CD pipeline generation, SousChef provides everything needed for a successful infrastructure automation migration.\n\n### 2. Ansible Upgrade Assessment \u0026 Planning (5 tools)\n\nComprehensive Ansible upgrade analysis and planning tools based on official Ansible-Python compatibility matrices:\n\n- **Version Compatibility Assessment** - Validate Ansible and Python version compatibility\n- **EOL Status Checking** - Track end-of-life dates and security support\n- **Upgrade Path Planning** - Generate detailed upgrade plans with risk assessment\n- **Collection Compatibility** - Validate collection versions against target Ansible releases\n- **Breaking Change Analysis** - Identify and plan for breaking changes (e.g., 2.9 → 2.10 collections split)\n- **Python Upgrade Impact** - Assess Python version upgrade requirements for control and managed nodes\n- **Testing Plan Generation** - Generate comprehensive upgrade testing plans\n\n\u003e **✅ Feature Status**: Ansible upgrade features are now available with CLI commands, MCP tools, and web UI.\n\u003e See [Ansible Upgrade Integration Design](docs/ANSIBLE_UPGRADE_INTEGRATION.md) for full details.\n\n### About Tool Counts\n\n**Why 43 tools in the documentation but more in the server?**\n\nThe MCP server provides **48 total tools**. This documentation focuses on the **43 primary user-facing tools** (38 migration + 5 upgrade tools) that cover the main capabilities. The remaining 5 are low-level filesystem operations used internally by the main tools.\n\nAs a user, you'll primarily interact with the documented tools. Your AI assistant may use the additional tools automatically when needed, but you don't need to know about them for successful migrations.\n\n\u003e **For developers:** See `souschef/server.py` for the complete list of all 48 registered tools.\n\n## Model Agnostic - Works with Any AI Model\n\n**SousChef works with ANY AI model through the Model Context Protocol (MCP)**. The MCP architecture separates tools from models:\n\n- **Red Hat AI** (Llama, IBM models)\n- **Claude** (Anthropic)\n- **GPT-4/GPT-3.5** (OpenAI)\n- **GitHub Copilot** (Microsoft/OpenAI)\n- **Local Models** (Ollama, llama.cpp, etc.)\n- **Custom Enterprise Models**\n\n**How it works:** You choose your AI model provider in your MCP client. SousChef provides the Chef/Ansible expertise through 43 specialized tools. The model calls these tools to help with your migration and upgrade planning.\n\n\u003e See [config/CONFIGURATION.md](config/CONFIGURATION.md) for configuration examples with different model providers.\n\n## Quick Links\n\n### Chef to Ansible Migration\n- **[Terraform Provider](terraform-provider/README.md)** - Manage migrations with infrastructure-as-code\n- **[User Guide](docs/user-guide/)** - Complete documentation\n- **[Data Persistence Guide](docs/user-guide/data-persistence.md)** - History, caching, and storage backends\n- **[API Reference](docs/api-reference/)** - Detailed tool documentation\n- **[Migration Guide](docs/migration-guide/)** - Step-by-step migration process\n\n### Ansible Upgrades\n- **[Ansible Upgrade Integration Design](docs/ANSIBLE_UPGRADE_INTEGRATION.md)** - Complete design and architecture\n- **[Ansible Upgrade Matrix Implementation](docs/ANSIBLE_UPGRADE_MATRIX_IMPLEMENTATION.md)** - PDF data mapping and implementation\n- **[Implementation Roadmap](docs/ANSIBLE_UPGRADE_ROADMAP.md)** - Detailed development timeline\n- **[User Guide](docs/user-guide/ansible-upgrades.md)** - Comprehensive usage guide\n\n## What's New in v5.0.0\n\n**Major Release: Ansible Upgrade \u0026 Planning Tools** - Complete upgrade assessment and planning capabilities:\n\n- **5 New CLI Commands**: `ansible assess`, `plan`, `eol`, `validate-collections`, `detect-python` for comprehensive upgrade workflows\n- **3 Interactive UI Pages**: Environment Assessment, Upgrade Planning, and Collection Validation interfaces\n- **MCP Tool Integration**: Access upgrade planning programmatically through MCP server tools\n- **Comprehensive Testing**: 1,954 passing tests with 91% coverage across all upgrade functionality\n- **Type Safety**: Full mypy compliance with proper type hints for all new functions\n- **Production Ready**: All quality gates passing - Ruff linting, mypy, and comprehensive test coverage\n\nSee [Ansible Upgrade Integration Design](docs/ANSIBLE_UPGRADE_INTEGRATION.md) for complete documentation.\n\n## Previous Releases\n\n### v4.1.0 - Security Hardening \u0026 Type Safety\n\nEnterprise-grade improvements for production deployments:\n\n- **GitHub Actions Security**: All external actions pinned to commit SHAs for supply chain protection\n- **Type Safety**: Complete mypy type checking (0 errors) with full type hints across 57 source files\n- **Fork Checkout Protection**: Privileged workflows explicitly checkout from main repository, never from forks\n- **Python Support Expansion**: Now supports Python 3.10+ (added support for 3.10 and 3.11)\n- **Code Quality**: Ruff linting with zero warnings, Australian English documentation standards\n\nSee [Release Notes](https://github.com/kpeacocke/souschef/releases/tag/v4.1.0) for full details.\n\n### v3.4.0 - Chef Server Integration\n\n**Chef Server Integration \u0026 AI-Enhanced Template Conversion** - Dynamic inventory and intelligent template conversion:\n\n- **Chef Server Connectivity**: Validate Chef Server connections and query nodes with `validate_chef_server_connection` and `get_chef_nodes`\n- **AI-Enhanced Templates**: Convert ERB to Jinja2 with AI validation using `convert_template_with_ai` for complex Ruby logic\n- **CLI Commands**: New commands `validate-chef-server`, `query-chef-nodes`, and `convert-template-ai` for command-line access\n- **Streamlit UI**: Chef Server Settings page for managing server configuration and validation\n\n## Installation\n\n```bash\n# PyPI Installation\npip install mcp-souschef\n\n# Development Installation\ngit clone https://github.com/kpeacocke/souschef.git\ncd souschef\npoetry install\n```\n\n\u003e **For detailed installation instructions, MCP setup, and configuration, see [Installation \u0026 Setup](#installation--setup)**\n\n## Core Capabilities\n\n### 1. Chef Cookbook Analysis \u0026 Parsing\n\nComplete cookbook introspection and analysis tools:\n\n- **parse_template** - Parse ERB templates with Jinja2 conversion and variable extraction\n- **parse_custom_resource** - Extract properties, attributes, and actions from custom resources and LWRPs\n- **list_directory** - Navigate and explore cookbook directory structures\n- **read_file** - Read cookbook files with error handling\n- **read_cookbook_metadata** - Parse metadata.rb files for dependencies and cookbook information\n- **parse_recipe** - Analyse Chef recipes and extract resources, actions, and properties\n- **parse_attributes** - Parse attribute files with **advanced precedence resolution** (6 levels: default, force_default, normal, override, force_override, automatic)\n- **list_cookbook_structure** - Display complete cookbook directory hierarchy\n\n### 2. Chef-to-Ansible Conversion Engine\n\nAdvanced resource-to-task conversion with intelligent module selection:\n\n- **convert_resource_to_task** - Transform individual Chef resources to Ansible tasks\n- **generate_playbook_from_recipe** - Generate complete Ansible playbooks from Chef recipes\n- **Enhanced Guard Handling** - Convert complex Chef guards to Ansible when/unless conditions\n  - Array-based guards: `only_if ['condition1', 'condition2']`\n  - Lambda/proc syntax: `only_if { ::File.exist?('/path') }`\n  - Do-end blocks: `not_if do ... end`\n  - Multiple guard types per resource with proper AND/OR logic\n  - Platform checks, node attributes, file/directory existence, and command execution\n\n### 3. Chef Search \u0026 Inventory Integration\n\nConvert Chef search patterns to dynamic Ansible inventory:\n\n- **convert_chef_search_to_inventory** - Transform Chef search queries to Ansible inventory groups\n- **generate_dynamic_inventory_script** - Create dynamic inventory scripts from Chef server queries\n- **analyse_chef_search_patterns** - Discover and analyse search usage in cookbooks\n\n### 4. InSpec Integration \u0026 Validation\n\nComplete InSpec-to-Ansible testing pipeline:\n\n- **parse_inspec_profile** - Parse InSpec profiles and extract controls\n- **convert_inspec_to_test** - Convert InSpec controls to Testinfra or Ansible assert tasks\n- **generate_inspec_from_recipe** - Auto-generate InSpec validation from Chef recipes\n\n### 5. Data Bags \u0026 Secrets Management\n\nChef data bags to Ansible vars/vault conversion:\n\n- **convert_chef_databag_to_vars** - Transform data bags to Ansible variable files\n- **generate_ansible_vault_from_databags** - Convert encrypted data bags to Ansible Vault\n- **analyse_chef_databag_usage** - Analyse data bag usage patterns in cookbooks\n\n### 6. Environment \u0026 Configuration Management\n\nChef environments to Ansible inventory groups:\n\n- **convert_chef_environment_to_inventory_group** - Transform Chef environments to inventory\n- **generate_inventory_from_chef_environments** - Generate complete inventory from environments\n- **analyse_chef_environment_usage** - Analyse environment usage in cookbooks\n\n### 7. AWX/Ansible Automation Platform Integration\n\nEnterprise AWX/AAP configuration generation:\n\n- **generate_awx_job_template_from_cookbook** - Create AWX job templates from cookbooks\n- **generate_awx_workflow_from_chef_runlist** - Transform Chef run-lists to AWX workflows\n- **generate_awx_project_from_cookbooks** - Generate AWX projects from cookbook collections\n- **generate_awx_inventory_source_from_chef** - Create dynamic inventory sources from Chef server\n\n### 8. Chef Habitat to Container Conversion\n\nModernize Habitat applications to containerized deployments:\n\n- **parse_habitat_plan** - Parse Chef Habitat plan files (plan.sh) and extract package metadata, dependencies, build/install hooks, and service configuration\n- **convert_habitat_to_dockerfile** - Convert Chef Habitat plans to production-ready Dockerfiles with security validation\n- **generate_compose_from_habitat** - Generate docker-compose.yml from multiple Habitat plans for multi-service deployments\n\n### 9. Advanced Deployment Patterns \u0026 Migration Assessment\n\nModern deployment strategies and migration planning:\n\n- **convert_chef_deployment_to_ansible_strategy** - Convert deployment recipes to Ansible strategies\n- **generate_blue_green_deployment_playbook** - Create blue/green deployment playbooks\n- **generate_canary_deployment_strategy** - Generate canary deployment configurations\n\n### 10. CI/CD Pipeline Generation\n\nGenerate Jenkins, GitLab CI, and GitHub Actions workflows from Chef cookbook CI patterns:\n\n- **generate_jenkinsfile_from_chef** - Generate Jenkinsfile (Declarative or Scripted) from Chef cookbook CI/CD patterns\n- **generate_gitlab_ci_from_chef** - Generate .gitlab-ci.yml from Chef cookbook testing tools\n- **generate_github_workflow_from_chef** - Generate GitHub Actions workflow from Chef cookbook CI/CD patterns\n\nAutomatically detects and converts:\n\n- **Test Kitchen** configurations (.kitchen.yml) → Integration test stages\n- **ChefSpec** tests (spec/) → Unit test stages\n- **Cookstyle/Foodcritic** → Lint stages\n- Multiple test suites → Parallel execution strategies\n\n### 11. GitHub Copilot Agent Control (🚧 Planned)\n\n🚧 **Planned for multi-platform orchestration** - Infrastructure for managing GitHub Copilot agent lifecycles across multiple platform migrations (Puppet, SaltStack, CFEngine → Ansible).\n\nThe API structure is stable (serving as specification for implementation), but helper functions currently use stub implementations. Full GitHub API integration will enable:\n\n- **Multi-repo migrations** - Orchestrate migrations across multiple repositories simultaneously\n- **Platform-specific agents** - Assign agents to tackle different platforms in parallel\n- **Progress tracking** - Monitor and control agent states during long-running migrations\n- **Automatic analysis** - Identify migration candidates in GitHub organisations\n\n**Planned capabilities:**\n\n- **assign_github_copilot_to_issue** - Assign Copilot agent to implement an issue\n- **pause_github_copilot_agent** - Pause a running agent (can be resumed)\n- **stop_github_copilot_agent** - Stop and cancel an agent assignment\n- **resume_github_copilot_agent** - Resume a paused agent with optional new instructions\n- **check_github_copilot_agent_status** - Check current agent state and activity\n\n**Planned agent lifecycle management:**\n\n1. **Assign** - Start Copilot working on an issue (e.g., \"Convert this Puppet module to Ansible\")\n2. **Monitor** - Check status and review progress across multiple platforms\n3. **Pause** - Temporarily pause for review or architectural adjustments\n4. **Resume** - Continue with optional new guidance (e.g., \"Also add Molecule tests\")\n5. **Stop** - Cancel if requirements change\n\nWhen implemented, state will be tracked via issue labels and comments, providing full visibility and control across distributed migration workflows.\n\n#### Example Usage - CI/CD Pipelines\n\n```bash\n# Generate Jenkins Declarative pipeline\nsouschef generate-jenkinsfile ./mycookbook\n\n# Generate Jenkins Scripted pipeline\nsouschef generate-jenkinsfile ./mycookbook --pipeline-type scripted\n\n# Generate GitLab CI configuration\nsouschef generate-gitlab-ci ./mycookbook\n\n# Generate GitHub Actions workflow\nsouschef generate-github-workflow ./mycookbook\n\n# Customise with options\nsouschef generate-gitlab-ci ./mycookbook --no-cache --no-artifacts\nsouschef generate-github-workflow ./mycookbook --workflow-name \"My CI\" --no-cache\n```\n\n#### Planned Example Usage - GitHub Agent Control (🚧 Future)\n\n```python\n# When implemented, from an AI assistant with SousChef MCP\n\n# Assign Copilot to convert a Puppet module to Ansible\nassign_github_copilot_to_issue(\n    owner=\"myorg\",\n    repo=\"my-ansible-repo\",\n    issue_number=42,\n    base_ref=\"main\",\n    custom_instructions=\"Convert this Puppet module to Ansible. Focus on idempotency.\"\n)\n\n# Check status across multiple platform migrations\ncheck_github_copilot_agent_status(\n    owner=\"myorg\",\n    repo=\"my-ansible-repo\",\n    issue_number=42\n)\n\n# Pause for architectural review\npause_github_copilot_agent(\n    owner=\"myorg\",\n    repo=\"my-ansible-repo\",\n    issue_number=42,\n    reason=\"Need to review module structure before continuing\"\n)\n\n# Resume with additional guidance\nresume_github_copilot_agent(\n    owner=\"myorg\",\n    repo=\"my-ansible-repo\",\n    issue_number=42,\n    additional_instructions=\"Also add Molecule tests and role dependencies\"\n)\n\n# Stop and manually implement\nstop_github_copilot_agent(\n    owner=\"myorg\",\n    repo=\"my-ansible-repo\",\n    issue_number=42,\n    reason=\"Requirements changed - using different pattern\"\n)\n```\n\n#### Command Line Usage - CI/CD Pipelines\n\n**MCP Tool Usage:**\n\n```python\n# From an AI assistant with SousChef MCP\n\n# Generate Jenkins pipeline\ngenerate_jenkinsfile_from_chef(\n    cookbook_path=\"/path/to/cookbook\",\n    pipeline_type=\"declarative\",  # or \"scripted\"\n    enable_parallel=\"yes\"  # or \"no\"\n)\n\n# Generate GitLab CI\ngenerate_gitlab_ci_from_chef(\n    cookbook_path=\"/path/to/cookbook\",\n    enable_cache=\"yes\",  # or \"no\"\n    enable_artifacts=\"yes\"  # or \"no\"\n)\n\n# Generate GitHub Actions workflow\ngenerate_github_workflow_from_chef(\n    cookbook_path=\"/path/to/cookbook\",\n    workflow_name=\"Chef Cookbook CI\",\n    enable_cache=\"yes\",  # or \"no\"\n    enable_artifacts=\"yes\"  # or \"no\"\n)\n```\n\n### 11. Conversion Validation Framework\n\nComprehensive validation of Chef-to-Ansible conversions:\n\n- **validate_conversion** - Validate conversions across multiple dimensions\n  - **Syntax Validation**: YAML, Jinja2, Python syntax checking\n  - **Semantic Validation**: Logic equivalence, variable usage, resource dependencies\n  - **Best Practice Checks**: Naming conventions, idempotency, task organization\n  - **Security Validation**: Privilege escalation patterns, sensitive data handling\n  - **Performance Recommendations**: Efficiency suggestions and optimizations\n\n#### Validation Levels\n\n- **ERROR**: Critical issues that will prevent execution\n- **WARNING**: Potential problems or anti-patterns that may cause issues\n- **INFO**: Suggestions for improvements and best practices\n\n#### Validation Categories\n\n- **Syntax**: Code structure and syntax correctness\n- **Semantic**: Logical equivalence and meaning preservation\n- **Best Practice**: Ansible community standards and patterns\n- **Security**: Security considerations and recommendations\n- **Performance**: Efficiency and optimization suggestions\n\n#### Validation Examples\n\n```python\n# Validate a resource conversion\nvalidate_conversion(\n    conversion_type=\"resource\",\n    result_content=\"\"\"- name: Install nginx\n  ansible.builtin.package:\n    name: \"nginx\"\n    state: present\n\"\"\",\n    output_format=\"text\"  # Options: text, json, summary\n)\n```\n\nOutput formats:\n\n- **text**: Detailed report with all findings grouped by severity\n- **json**: Structured JSON for programmatic processing\n- **summary**: Quick overview with counts only\n\n- **analyse_chef_application_patterns** - Identify application deployment patterns\n- **assess_chef_migration_complexity** - Comprehensive migration complexity assessment\n- **generate_migration_plan** - Create detailed migration execution plans\n- **analyse_cookbook_dependencies** - Analyse dependencies and migration order\n- **generate_migration_report** - Generate executive and technical migration reports\n\n### 12. Chef Server Integration \u0026 Dynamic Inventory\n\nDynamic inventory generation and Chef Server connectivity for hybrid environments:\n\n- **validate_chef_server_connection** - Test Chef Server REST API connectivity and authentication\n- **get_chef_nodes** - Query Chef Server for nodes matching search criteria, extracting roles, environment, platform, and IP information\n- **convert_template_with_ai** - Convert ERB templates to Jinja2 with AI-based validation for complex Ruby logic\n\n#### Chef Server Features\n\n- **Connection Validation**: Test Chef Server connectivity before migrations\n- **Dynamic Node Queries**: Search Chef Server by role, environment, or custom attributes\n- **Node Metadata Extraction**: Retrieve IP addresses, FQDNs, platforms, and roles for inventory\n- **AI-Enhanced Conversion**: Intelligent ERB→Jinja2 conversion with validation for complex Ruby constructs\n- **Fallback Handling**: Graceful degradation when Chef Server is unavailable\n\n#### Usage Examples\n\n```bash\n# Validate Chef Server connection\nsouschef validate-chef-server --server-url https://chef.example.com --node-name admin\n\n# Query Chef Server for nodes\nsouschef query-chef-nodes --search-query \"role:web_server\" --json\n\n# Convert template with AI assistance\nsouschef convert-template-ai /path/to/template.erb --ai --output /path/to/output.j2\n```\n\n#### MCP Tool Usage\n\n```python\n# Validate Chef Server from AI assistant\nvalidate_chef_server_connection(\n    server_url=\"https://chef.example.com\",\n    node_name=\"admin\"\n)\n\n# Query nodes for dynamic inventory\nget_chef_nodes(search_query=\"role:web_server AND environment:production\")\n\n# Convert template with AI validation\nconvert_template_with_ai(\n    erb_path=\"/path/to/template.erb\",\n    use_ai_enhancement=True\n)\n```\n\n### 13. Ansible Upgrade Assessment \u0026 Planning\n\nComprehensive Ansible version upgrade planning based on official Ansible-Python compatibility matrices:\n\n- **detect_python_version** - Detect Python version in specified environment or system\n- **assess_ansible_environment** - Assess current Ansible environment versions and configuration\n- **generate_upgrade_plan** - Generate detailed upgrade plan with breaking changes, pre/post checks, and risk assessment\n- **validate_collection_compatibility** - Validate Ansible collection compatibility against target Ansible versions\n- **generate_upgrade_testing_plan** - Generate comprehensive upgrade testing plan\n\n#### Upgrade Planning Features\n\n- **Version Compatibility Checking**: Validate Ansible and Python version compatibility requirements\n- **EOL Status Tracking**: Track end-of-life dates and security support windows\n- **Safe Upgrade Paths**: Calculate safe upgrade paths with intermediate versions if needed\n- **Breaking Change Analysis**: Identify breaking changes (e.g., collections split in 2.9→2.10)\n- **Collection Validation**: Verify collection versions work with target Ansible releases\n- **Python Impact Assessment**: Assess Python version upgrade requirements for control and managed nodes\n- **Comprehensive Testing Plans**: Generate step-by-step testing procedures for upgrades\n\n#### Upgrade Planning Examples\n\n```bash\n# Detect Python version in environment\ndetect_python_version /path/to/venv\n\n# Assess current Ansible environment\nassess_ansible_environment /path/to/ansible/env\n\n# Generate upgrade plan from 2.14 to 2.17\ngenerate_upgrade_plan 2.14 2.17 /path/to/ansible/env\n\n# Validate collections for target version\nvalidate_collection_compatibility '{\"community.general\": \"3.0.0\"}' 2.17\n\n# Generate testing plan for upgrade\ngenerate_upgrade_testing_plan /path/to/ansible/env\n```\n\n#### MCP Tool Usage\n\n```python\n# From an AI assistant with SousChef MCP\n\n# Detect Python version\npython_version = detect_python_version(\"/ansible/venv\")\n\n# Assess Ansible environment\nassessment = assess_ansible_environment(\"/ansible/env\")\n\n# Generate upgrade plan\nplan = generate_upgrade_plan(\n    current_version=\"2.14\",\n    target_version=\"2.17\"\n)\n\n# Check collection compatibility\ncompatibility = validate_collection_compatibility(\n    collections={\"community.general\": \"3.0.0\"},\n    ansible_version=\"2.17\"\n)\n\n# Generate testing plan\ntesting_plan = generate_upgrade_testing_plan(\"/ansible/env\")\n```\n\n**See [Ansible Upgrade Integration Design](docs/ANSIBLE_UPGRADE_INTEGRATION.md) for full details and compatibility matrix information.**\n\n## Migration Workflow\n\n### Phase 1: Discovery \u0026 Assessment\n\n```bash\n# Assess migration complexity\nassess_chef_migration_complexity /path/to/cookbooks\n\n# Analyse cookbook dependencies\nanalyse_cookbook_dependencies /path/to/cookbook\n\n# Generate migration plan\ngenerate_migration_plan '{\\\"cookbooks\\\": [\\\"/path/to/cookbook1\\\", \\\"/path/to/cookbook2\\\"]}'\n```\n\n### Phase 2: Content Conversion\n\n```bash\n# Convert recipes to playbooks\ngenerate_playbook_from_recipe /path/to/recipe.rb\n\n# Convert data bags to Ansible Vault\ngenerate_ansible_vault_from_databags /path/to/databags\n\n# Convert environments to inventory\ngenerate_inventory_from_chef_environments /path/to/environments\n```\n\n### Phase 3: AWX/AAP Integration\n\n```bash\n# Generate AWX job templates\ngenerate_awx_job_template_from_cookbook /path/to/cookbook cookbook_name\n\n# Create AWX workflows from run-lists\ngenerate_awx_workflow_from_chef_runlist \\\"recipe[app::deploy]\\\" workflow_name\n\n# Setup dynamic inventory from Chef server\ngenerate_awx_inventory_source_from_chef https://chef.example.com production web_servers\n```\n\n### Phase 4: Habitat to Container Migration\n\n```bash\n# Parse Habitat plan\nparse_habitat_plan /path/to/plan.sh\n\n# Convert to Dockerfile\nconvert_habitat_to_dockerfile /path/to/plan.sh ubuntu:22.04 false\n\n# Generate docker-compose for multiple services\ngenerate_compose_from_habitat \"/path/to/plan1.sh,/path/to/plan2.sh\" my_network\n```\n\n### Phase 5: Validation \u0026 Testing\n\n```bash\n# Generate InSpec validation\ngenerate_inspec_from_recipe /path/to/recipe.rb\n\n# Convert existing InSpec to Ansible tests\nconvert_inspec_to_test /path/to/inspec_profile testinfra\n```\n\n### Performance Profiling \u0026 Optimization\n\nProfile cookbook parsing performance to identify bottlenecks and optimize large-scale migrations:\n\n```bash\n# Profile entire cookbook (all parsing operations)\nsouschef-cli profile /path/to/cookbook\n\n# Save profiling report to file\nsouschef-cli profile /path/to/cookbook --output profile_report.txt\n\n# Profile specific operations with detailed statistics\nsouschef-cli profile-operation recipe /path/to/recipe.rb --detailed\nsouschef-cli profile-operation attributes /path/to/attributes/default.rb\nsouschef-cli profile-operation template /path/to/template.erb\n\n# MCP Tool Usage (from AI assistants)\nprofile_cookbook_performance /path/to/large_cookbook\nprofile_parsing_operation recipe /path/to/recipe.rb --detailed\n```\n\n### 10. Visual Migration Planning Interface\n\nInteractive web-based interface for Chef-to-Ansible migration planning and Ansible upgrade management:\n\n**Chef Migration Features:**\n- **Cookbook Analysis Dashboard**: Interactive directory scanning with metadata parsing and complexity assessment\n- **AI-Assisted Effort Estimation** (v3.3.0+):\n  - **Manual Migration Estimate**: Full effort without AI assistance\n  - **SousChef-Assisted Estimate**: 50% time reduction through automated boilerplate conversion\n  - **Time Savings Display**: Clear comparison showing hours saved and efficiency percentage\n  - **Visual Metrics**: Side-by-side metric cards for instant visual comparison\n- **Migration Planning Wizard**: Step-by-step migration planning with dual effort scenarios and risk analysis\n- **Dependency Mapping**: Visual dependency graphs showing cookbook relationships and migration ordering\n- **Validation Reports**: Conversion validation results with syntax checking and best practice compliance\n- **Progress Tracking**: Real-time migration progress with completion metrics and bottleneck identification\n- **History and Persistence**: Stored analysis history, cached results, and downloadable artefacts (SQLite or PostgreSQL, plus S3-compatible storage)\n\n**Ansible Upgrade Features (NEW):**\n- **Environment Assessment**: Analyse current Ansible installation, Python compatibility, and installed collections\n- **Upgrade Planning**: Interactive upgrade planning with version selection, breaking changes analysis, and risk assessment\n- **Collection Validation**: Upload requirements.yml to validate collection compatibility with target Ansible versions\n- **Visual Dashboards**: Progress bars, compatibility metrics, and exportable JSON reports for all upgrade assessments\n\n**Launch the UI:**\n\n```bash\n# Using Poetry (development)\npoetry run souschef ui\n\n# Using pip (installed)\nsouschef ui\n\n# Custom port\nsouschef ui --port 8080\n```\n\n## Docker Images Overview\n\nSousChef provides **two complementary Docker images** for different use cases:\n\n| Image | Purpose | Use When | Docker File |\n|-------|---------|----------|-------------|\n| **souschef** | Web UI (Streamlit) | You want an interactive web dashboard for Chef-to-Ansible migration planning and execution | `Dockerfile` |\n| **souschef-mcp** | MCP Server (stdio protocol) | You want to use SousChef with Claude Desktop, VS Code GitHub Copilot, or other MCP-compatible AI tools | `Dockerfile.mcp` |\n\n### Building Docker Images Locally\n\n**Build the Web UI:**\n\n```bash\n# Build the Streamlit web UI image\ndocker build -t souschef .\n\n# Run the UI on port 9999\ndocker run -p 9999:9999 souschef\n\n# Or use docker-compose for full stack (with database and storage)\ndocker-compose up\n```\n\n**Build the MCP Server:**\n\n```bash\n# Build the MCP server image\ndocker build -f Dockerfile.mcp -t souschef-mcp:latest .\n\n# Run the MCP server over stdio (for AI clients)\ndocker run -i --rm souschef-mcp:latest\n```\n\nUse the Docker configuration examples to connect your MCP client:\n\n- [config/claude-desktop-docker.json](config/claude-desktop-docker.json) - Claude Desktop configuration\n- [config/vscode-copilot-docker.json](config/vscode-copilot-docker.json) - VS Code GitHub Copilot configuration\n\n### Using Published Docker Images\n\nSousChef publishes both Docker images to GHCR on each release with:\n\n**1. SousChef Web UI (`souschef`):**\n\nThe interactive Streamlit web dashboard for Chef-to-Ansible migration planning and execution.\n\n```bash\n# Pull and run the UI\ndocker pull ghcr.io/kpeacocke/souschef:latest\ndocker run -p 9999:9999 \\\n  --env-file .env \\\n  ghcr.io/kpeacocke/souschef:latest\n\n# Visit http://localhost:9999 in your browser\n```\n\n**2. SousChef MCP Server (`souschef-mcp`):**\n\nThe headless MCP server for integration with AI assistants and automation tools.\n\n```bash\n# Pull and run the MCP server\ndocker pull ghcr.io/kpeacocke/souschef-mcp:latest\ndocker run -i --rm ghcr.io/kpeacocke/souschef-mcp:latest\n```\n\nUse this with:\n\n- [Claude Desktop](https://claude.ai/download) via `config/claude-desktop-docker-ghcr.json`\n- [VS Code GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) via `config/vscode-copilot-docker-ghcr.json`\n- Other MCP-compatible tools via stdio protocol\n\n**Container Images:**\n\n- **Registry**: GitHub Container Registry (GHCR)\n- **UI Image**: `ghcr.io/kpeacocke/souschef` (Streamlit web interface)\n- **MCP Server Image**: `ghcr.io/kpeacocke/souschef-mcp` (stdio MCP protocol)\n- **Available Tags**:\n  - `latest` - Most recent release\n  - `4.1.2` - Specific version (semver)\n  - `4.1` - Latest patch of a minor version\n  - `4` - Latest patch of a major version\n\n**Why use GHCR?**\n\n- Integrated with GitHub releases and CI/CD\n- Faster pulls for users in GitHub ecosystem\n- Security scanning and SBOM included\n- Multi-platform support (amd64, arm64)\n\n**Container Security Scanning:**\n\nAll Docker images are automatically scanned for vulnerabilities using Trivy during the release process:\n\n- **Automated Scanning**: Every release build includes vulnerability scanning\n- **Smart Filtering**: Only CRITICAL/HIGH severity vulnerabilities with available fixes are reported\n- **Zero Unfixed Issues**: Uses `ignore-unfixed: true` to filter noise from base image issues awaiting upstream patches\n- **GitHub Security Tab**: Scan results available in the repository's Security tab for tracking and monitoring\n- **Transparent Process**: All vulnerability scanning is documented in `.trivyignore`\n\nFor details on vulnerability management and security practices, see [SECURITY.md](SECURITY.md#automated-vulnerability-scanning).\n\n**Docker Environment Configuration:**\n\nSousChef supports AI configuration via environment variables in Docker containers. Create a `.env` file in your project root:\n\n```bash\n# Copy the example environment file\ncp .env.example .env\n\n# Edit with your AI provider settings\nnano .env\n```\n\n**Example .env file:**\n\n```dotenv\n# AI Configuration\nSOUSCHEF_AI_PROVIDER=Anthropic (Claude)\nSOUSCHEF_AI_MODEL=claude-3-5-sonnet-20241022\nSOUSCHEF_AI_API_KEY=your-api-key-here\nSOUSCHEF_AI_BASE_URL=\nSOUSCHEF_AI_PROJECT_ID=\nSOUSCHEF_AI_TEMPERATURE=0.7\nSOUSCHEF_AI_MAX_TOKENS=4000\nSOUSCHEF_ALLOWED_HOSTNAMES=api.example.com,*.example.org\n\n# Streamlit Configuration (optional)\nSTREAMLIT_SERVER_PORT=9999\nSTREAMLIT_SERVER_HEADLESS=true\n```\n\n**Supported AI Providers:**\n\n- `Anthropic (Claude)` - Anthropic Claude models\n- `OpenAI (GPT)` - OpenAI GPT models\n- `IBM Watsonx` - IBM Watsonx AI models\n- `Red Hat Lightspeed` - Red Hat Lightspeed models\n\n**Environment Variables:**\n\n- `SOUSCHEF_AI_PROVIDER` - AI provider name (required)\n- `SOUSCHEF_AI_MODEL` - Model name (required)\n- `SOUSCHEF_AI_API_KEY` - API key for authentication (required)\n- `SOUSCHEF_AI_BASE_URL` - Custom API base URL (optional)\n- `SOUSCHEF_AI_PROJECT_ID` - Project ID for Watsonx (optional)\n- `SOUSCHEF_AI_TEMPERATURE` - Model temperature 0.0-2.0 (optional, default: 0.7)\n- `SOUSCHEF_AI_MAX_TOKENS` - Maximum tokens to generate (optional, default: 4000)\n- `SOUSCHEF_ALLOWED_HOSTNAMES` - Comma-separated list of allowed hostnames for outbound API requests (optional)\n\n**Persistent Storage Configuration (Docker Compose):**\n\nAll persistent storage paths are configurable via environment variables. Add these to your `.env` file to customise where data is stored:\n\n```dotenv\n# Docker Compose Volume Configuration (optional)\nSOUSCHEF_DATA_DIR=./data/souschef       # SQLite database and analysis history\nSOUSCHEF_STORAGE_DIR=./data/storage     # Generated artefacts and conversions\nPOSTGRES_DATA_DIR=./data/postgres       # PostgreSQL database files\nMINIO_DATA_DIR=./data/minio             # MinIO object storage data\n```\n\nThe storage paths default to `./data/` subdirectories (relative to docker-compose.yml) but can be set to any absolute or relative path. This allows you to:\n- Store data on different volumes or network storage\n- Easily backup and restore data by copying directories\n- Share data between development and production environments\n\nSee [Docker Deployment Guide](docs/docker-deployment.md#persistent-storage-configuration) for detailed configuration options.\n\n**Docker Compose (recommended for development):**\n\n```bash\n# Using PostgreSQL (default, production-ready)\ndocker compose up\n\n# Or if you prefer SQLite (lightweight, local storage only):\n# 1. Set in .env: SOUSCHEF_DB_BACKEND=sqlite\n# 2. Run normally: docker compose up\n```\n\n**Database Options:**\n\n- **PostgreSQL** (default):\n  - Robust, production-ready database server\n  - Recommended for all deployments\n  - Better concurrency and performance\n  - Data stored in `./data/postgres/`\n\n- **SQLite**:\n  - Lightweight, embedded database\n  - Good for development and testing\n  - Set `SOUSCHEF_DB_BACKEND=sqlite` in .env\n  - Data stored in `./data/souschef/`\n\n**Example with SQLite:**\n```bash\n# In .env, set:\nSOUSCHEF_DB_BACKEND=sqlite\n# Then start normally:\ndocker compose up\n```\n\n**Example with PostgreSQL (default):**\n```yaml\nversion: '3.8'\nservices:\n  souschef-ui:\n    build: .\n    ports:\n      - \"9999:9999\"\n    env_file:\n      - .env\n    environment:\n      - PYTHONPATH=/app\n      - STREAMLIT_SERVER_ADDRESS=0.0.0.0\n      - STREAMLIT_SERVER_PORT=9999\n      - STREAMLIT_SERVER_HEADLESS=true\n      - SOUSCHEF_DB_BACKEND=postgres\n      - SOUSCHEF_DB_HOST=postgres\n      - SOUSCHEF_DB_PORT=5432\n      - SOUSCHEF_DB_NAME=souschef\n      - SOUSCHEF_DB_USER=souschef\n      - SOUSCHEF_DB_PASSWORD=change-me\n    restart: unless-stopped\n```\n\n**Features:**\n\n- Clean, professional design matching documentation standards\n- Real-time cookbook analysis with progress indicators\n- **Interactive dependency visualization** with Plotly graphs and NetworkX analysis\n- **Static graph visualization** with matplotlib for reports and documentation\n- **Real-time progress tracking** for all analysis operations\n- Migration planning wizards with effort estimation\n- Validation reporting dashboard with conversion quality metrics\n- Cross-platform compatibility (Linux, macOS, Windows)\n\n### Advanced UI Features\n\n#### Interactive Dependency Visualization\n\nThe UI includes sophisticated dependency graph visualization powered by NetworkX and Plotly:\n\n- **Graph Analysis**: Automatic detection of cookbook dependencies, circular references, and migration ordering\n- **Interactive Exploration**: Zoom, pan, and hover over nodes to explore complex dependency relationships\n- **Color Coding**: Visual distinction between cookbooks, dependencies, community cookbooks, and circular dependencies\n- **Static Export**: Matplotlib-based static graphs for reports and documentation\n- **Large Graph Support**: Optimised layouts for complex cookbook ecosystems\n\n#### Real-Time Progress Tracking\n\nAll analysis operations include comprehensive progress feedback:\n\n- **Progress Bars**: Visual progress indicators for long-running operations\n- **Status Updates**: Real-time status messages during analysis phases\n- **Operation Tracking**: Separate progress tracking for dependency analysis, validation, and migration planning\n- **Error Handling**: Graceful error display with recovery suggestions\n\n#### Enhanced User Experience\n\n- **Responsive Design**: Clean, professional interface that works across different screen sizes\n- **Export Options**: Download analysis results, graphs, and migration plans\n- **Session Persistence**: Maintain analysis state across page refreshes\n- **Quick Actions**: One-click access to common migration tasks\n\n### Migration Assessment \u0026 Reporting\n\n- **Complexity Analysis**: Automated assessment of migration effort and risk factors\n- **Dependency Mapping**: Complete cookbook dependency analysis with migration ordering\n- **Impact Analysis**: Resource usage patterns and conversion recommendations\n- **Executive Reports**: Stakeholder-ready migration reports with timelines and costs\n\n### Modern Deployment Patterns\n\n- **Blue/Green Deployments**: Zero-downtime deployment strategies\n- **Canary Releases**: Gradual rollout configurations\n- **Application Patterns**: Modern containerized and cloud-native deployment patterns\n- **Rollback Strategies**: Automated failure recovery procedures\n- **Habitat to Container**: Convert Chef Habitat plans to Docker and Docker Compose configurations\n\n### Enterprise Integration\n\n- **AWX/AAP Ready**: Native Ansible Automation Platform integration\n- **Dynamic Inventory**: Chef server integration for hybrid environments\n- **Secrets Management**: Secure data bag to Vault conversion\n- **Multi-Environment**: Production-ready inventory and variable management\n\n## Installation \u0026 Setup\n\n### Prerequisites\n\n- Python 3.10+\n- [Poetry](https://python-poetry.org/) for dependency management\n- MCP-compatible client (Claude Desktop, VS Code 1.102+ with GitHub Copilot, etc.)\n\n### Quick Start\n\n1. **Install SousChef**:\n\n   ```bash\n   pip install mcp-souschef\n   ```\n\n2. **Configure Your MCP Client**:\n\n   Use the pre-configured files in the `config/` directory for quick setup with Claude Desktop, VS Code Copilot, or other MCP clients.\n\n   **Claude Desktop** (macOS):\n\n   ```bash\n   cp config/claude-desktop.json ~/Library/Application\\ Support/Claude/claude_desktop_config.json\n   # Restart Claude Desktop\n   ```\n\n   **Claude Desktop (Docker - published image):**\n\n   ```bash\n   cp config/claude-desktop-docker-ghcr.json ~/Library/Application\\ Support/Claude/claude_desktop_config.json\n   # Restart Claude Desktop\n   ```\n\n   **VS Code + GitHub Copilot** (requires VS Code 1.102+):\n\n   ```bash\n   # macOS/Linux\n   cp config/vscode-copilot.json ~/.config/Code/User/mcp.json\n\n   # Windows\n   copy config\\vscode-copilot.json %APPDATA%\\Code\\User\\mcp.json\n\n   # Reload VS Code window, then trust the server when prompted\n   ```\n\n   **VS Code + GitHub Copilot (Docker - published image):**\n\n   ```bash\n   # macOS/Linux\n   cp config/vscode-copilot-docker-ghcr.json ~/.config/Code/User/mcp.json\n\n   # Windows\n   copy config\\vscode-copilot-docker-ghcr.json %APPDATA%\\Code\\User\\mcp.json\n\n   # Reload VS Code window, then trust the server when prompted\n   ```\n\n   **See [config/CONFIGURATION.md](config/CONFIGURATION.md) for:**\n   - Platform-specific setup (macOS/Linux/Windows)\n   - Model provider configurations (Red Hat AI, OpenAI, local models)\n   - Development setup\n   - Troubleshooting\n\n3. **Start Using SousChef**:\n   - Restart your MCP client\n   - Ask: \"What Chef migration tools are available?\"\n   - Begin analyzing your cookbooks!\n\n### Command Line Interface (CLI)\n\nSousChef includes a standalone CLI for direct cookbook parsing and conversion:\n\n```bash\n# Basic usage examples\nsouschef-cli --help\nsouschef-cli recipe /path/to/recipe.rb\nsouschef-cli template /path/to/template.erb\nsouschef-cli convert package nginx --action install\nsouschef-cli cookbook /path/to/cookbook\n\n# Parse and convert with output formats\nsouschef-cli recipe recipe.rb --format json\nsouschef-cli inspec-generate recipe.rb \u003e validation.rb\nsouschef-cli inspec-convert controls.rb --format testinfra\n```\n\n**Available Commands:**\n\n**Chef Migration:**\n- `recipe` - Parse Chef recipe files and extract resources\n- `template` - Convert ERB templates to Jinja2 with variable extraction\n- `resource` - Parse custom resources and LWRPs\n- `attributes` - Extract Chef attribute definitions\n- `metadata` - Parse cookbook metadata.rb files\n- `structure` - Display cookbook directory structure\n- `convert` - Convert Chef resources to Ansible tasks\n- `cookbook` - Comprehensive cookbook analysis\n- `inspec-parse` - Parse InSpec profiles and controls\n- `inspec-convert` - Convert InSpec to Testinfra/Ansible tests\n- `inspec-generate` - Generate InSpec validation from recipes\n- `ls` / `cat` - File system operations\n\n**Ansible Upgrades:**\n- `ansible assess` - Assess current Ansible environment and version compatibility\n- `ansible plan` - Generate detailed upgrade plan between Ansible versions\n- `ansible eol` - Check end-of-life status for Ansible versions\n- `ansible validate-collections` - Validate collection compatibility with target version\n- `ansible detect-python` - Detect Python version in Ansible environment\n\n**User Interfaces:**\n- `ui` - Launch the Visual Migration Planning Interface\n\n#### Ansible CLI Examples\n\n**Environment Assessment:**\n```bash\n# Assess current Ansible environment\nsouschef ansible assess --environment-path /path/to/ansible\n\n# Example output:\n# - Detected Ansible version and Python version\n# - Lists all installed collections\n# - Warns about EOL versions\n# - Exports results to JSON\n```\n\n**Upgrade Planning:**\n```bash\n# Generate upgrade plan from Ansible 2.9 to 2.17\nsouschef ansible plan --current 2.9 --target 2.17\n\n# Example output:\n# - Breaking changes by category\n# - Deprecated features with alternatives\n# - Collection compatibility analysis\n# - Testing recommendations\n# - Risk assessment\n```\n\n**EOL Status:**\n```bash\n# Check if Ansible 2.9 is end-of-life\nsouschef ansible eol --version 2.9\n\n# Example output:\n# - EOL status and date\n# - Community/Core edition info\n# - Recommended upgrade paths\n```\n\n**Collection Validation:**\n```bash\n# Validate collections from requirements.yml\nsouschef ansible validate-collections --requirements-file requirements.yml --ansible-version 2.17\n\n# Example output:\n# - Compatibility status for each collection\n# - Breaking changes detected\n# - Dependency conflicts\n# - Recommended collection versions\n```\n\n**Python Detection:**\n```bash\n# Detect Python version in Ansible environment\nsouschef ansible detect-python --environment-path /path/to/ansible\n\n# Example output:\n# - Python version used by Ansible\n# - Compatibility with target Ansible version\n# - Required Python version for upgrade\n```\n\n### Development Setup\n\n```bash\n# Install dependencies\npoetry install\n\n# Install pre-commit hooks (one-time - auto-handles poetry.lock)\npoetry run pre-commit install\n\n# Run tests\npoetry run pytest\n\n# Run with coverage\npoetry run pytest --cov=souschef --cov-report=html\n\n# Lint and format\npoetry run ruff check .\npoetry run ruff format .\n\n# Type check\npoetry run mypy souschef\n```\n\n### **Dependency Management**\n\nPoetry manages dependencies with **automatic lock file synchronization**:\n\n```bash\n# Add dependencies\npoetry add package-name              # Production\npoetry add --group dev package-name  # Development\n\n# Update lock file after manual pyproject.toml edits\npoetry lock  # Poetry 2.x preserves versions automatically\n\n# Update dependencies\npoetry update package-name  # Specific package\npoetry update              # All packages\n```\n\n**Automated Systems:**\n\n- Pre-commit hooks auto-update `poetry.lock` when `pyproject.toml` changes\n- CI validates lock file on every PR\n- Dependabot sends weekly dependency updates\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md#-managing-dependencies) for detailed dependency management guide.\n\n## Architecture \u0026 Design\n\n### MCP Protocol Integration\n\nSousChef leverages the Model Context Protocol (MCP) to provide seamless integration with AI assistants and development environments:\n\n- **38 Specialized Tools**: Each migration capability exposed as dedicated MCP tool\n- **Type-Safe Interfaces**: Full Python type hints for reliable AI interactions\n- **Comprehensive Error Handling**: Graceful degradation and helpful error messages\n- **Streaming Support**: Efficient handling of large cookbook conversions\n\n### Testing Strategy\n\nFollowing enterprise-grade testing standards with comprehensive test coverage:\n\n- **Unit Tests**: Mock-based testing for individual functions (test_server.py, test_cli.py, test_mcp.py)\n- **Integration Tests**: Real cookbook testing with fixtures (test_integration.py, test_integration_accuracy.py)\n- **Property-Based Tests**: Hypothesis fuzz testing for edge cases (test_property_based.py)\n- **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)\n- **Performance Tests**: Benchmarking and optimization validation (test_performance.py)\n- **Snapshot Tests**: Regression testing for output stability (test_snapshots.py)\n- **83% Coverage**: Comprehensive test coverage approaching the 90% target for production readiness\n\n### Quality Assurance\n\n- **Zero Warnings Policy**: All code passes linting without disabling checks\n- **Type Safety**: Complete type annotations throughout the codebase\n- **Automated Testing**: CI/CD pipeline with comprehensive test suites\n- **Documentation**: Detailed docstrings and usage examples\n\n## Documentation\n\n### Tool Reference\n\nEach MCP tool includes comprehensive documentation:\n\n- Purpose and use cases\n- Parameter descriptions and types\n- Return value specifications\n- Usage examples and patterns\n- Error handling behaviors\n\n### Migration Guides\n\n- **[Enterprise Migration Guide](docs/enterprise-migration.md)** - Complete methodology for large-scale migrations\n- **[AWX Integration Guide](docs/awx-integration.md)** - Step-by-step AWX/AAP setup and configuration\n- **[Testing Strategy Guide](docs/testing-strategy.md)** - Validation and testing approaches\n- **[Best Practices](docs/best-practices.md)** - Recommended patterns and approaches\n\n## Support \u0026 Community\n\n- **Issues**: [GitHub Issues](https://github.com/kpeacocke/souschef/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/kpeacocke/souschef/discussions)\n- **Documentation**: [Wiki](https://github.com/kpeacocke/souschef/wiki)\n\n---\n\n## SousChef\n\n- `default` - Default value if specified\n- `required` - Whether the property is required (true/false)\n\n**Action Extraction:**\n\n- Modern format: `action :name do ... end`\n- LWRP format: `actions :create, :delete, :update`\n- Supports both formats and mixed declarations\n\n### `convert_resource_to_task(resource_type: str, resource_name: str, action: str = \"create\", properties: str = \"\")`\n\nConvert a Chef resource to an Ansible task.\n\n**Example:**\n\n```python\nconvert_resource_to_task(\"package\", \"nginx\", \"install\")\n# Returns:\n# - name: Install package nginx\n#   ansible.builtin.package:\n#     name: \"nginx\"\n#     state: \"present\"\n\nconvert_resource_to_task(\"service\", \"nginx\", \"start\")\n# Returns:\n# - name: Start service nginx\n#   ansible.builtin.service:\n#     name: \"nginx\"\n#     enabled: true\n#     state: \"started\"\n\nconvert_resource_to_task(\"template\", \"/etc/nginx/nginx.conf.erb\", \"create\")\n# Returns:\n# - name: Create template /etc/nginx/nginx.conf.erb\n#   ansible.builtin.template:\n#     src: \"/etc/nginx/nginx.conf.erb\"\n#     dest: \"/etc/nginx/nginx.conf\"\n#     mode: \"0644\"\n```\n\n**Supported Resource Types:**\n\n- `package` → `ansible.builtin.package`\n- `service` → `ansible.builtin.service`\n- `template` → `ansible.builtin.template`\n- `file` → `ansible.builtin.file`\n- `directory` → `ansible.builtin.file` (with state: directory)\n- `execute` → `ansible.builtin.command`\n- `bash` → `ansible.builtin.shell`\n- `user` → `ansible.builtin.user`\n- `group` → `ansible.builtin.group`\n- And more...\n\n#### `parse_habitat_plan(plan_path: str)`\n\nParse a Chef Habitat plan file (plan.sh) and extract package metadata, dependencies, build/install hooks, and service configuration.\n\n**Example:**\n\n```python\nparse_habitat_plan(\"/path/to/habitat/plan.sh\")\n# Returns JSON with:\n# {\n#   \"package\": {\n#     \"name\": \"nginx\",\n#     \"origin\": \"core\",\n#     \"version\": \"1.25.3\",\n#     \"maintainer\": \"The Habitat Maintainers\",\n#     \"description\": \"High-performance HTTP server\"\n#   },\n#   \"dependencies\": {\n#     \"build\": [\"core/gcc\", \"core/make\"],\n#     \"runtime\": [\"core/glibc\", \"core/openssl\"]\n#   },\n#   \"ports\": [\n#     {\"name\": \"http\", \"value\": \"http.port\"},\n#     {\"name\": \"https\", \"value\": \"http.ssl_port\"}\n#   ],\n#   \"binds\": [\n#     {\"name\": \"database\", \"value\": \"postgresql.default\"}\n#   ],\n#   \"service\": {\n#     \"run\": \"nginx -g 'daemon off;'\",\n#     \"user\": \"nginx\"\n#   },\n#   \"callbacks\": {\n#     \"do_build\": \"./configure --prefix=/usr/local\\nmake\",\n#     \"do_install\": \"make install\",\n#     \"do_init\": \"mkdir -p /var/lib/nginx\"\n#   }\n# }\n```\n\n**Extracted Information:**\n\n- **Package metadata**: name, origin, version, maintainer, description\n- **Dependencies**: Build-time and runtime package dependencies\n- **Ports**: Exported port configurations for service discovery\n- **Binds**: Service bindings to other Habitat services\n- **Service configuration**: Run command, user, and initialization scripts\n- **Build callbacks**: do_build, do_install, do_init, and other lifecycle hooks\n\n**Use Cases:**\n\n- Understanding Habitat application structure before containerization\n- Extracting dependencies for Docker base image selection\n- Planning port mappings for docker-compose configurations\n- Analyzing service dependencies and orchestration needs\n\n#### `convert_habitat_to_dockerfile(plan_path: str, base_image: str = \"ubuntu:22.04\", allow_dangerous_patterns: bool = False)`\n\nConvert a Chef Habitat plan to a production-ready Dockerfile with security validation.\n\nDangerous shell patterns (for example, curl or wget piped to sh) are blocked by default. Set `allow_dangerous_patterns=True` only for trusted plans after review.\n\n**Example:**\n\n```python\nconvert_habitat_to_dockerfile(\"/path/to/habitat/plan.sh\", \"ubuntu:22.04\", False)\n# Returns:\n# # Dockerfile generated from Habitat plan\n# # Original plan: plan.sh\n# # Package: core/nginx\n# # Version: 1.25.3\n#\n# FROM ubuntu:22.04\n#\n# LABEL maintainer=\"The Habitat Maintainers\"\n# LABEL version=\"1.25.3\"\n#\n# # Install dependencies\n# RUN apt-get update \u0026\u0026 apt-get install -y --no-install-recommends \\\n#     gcc \\\n#     make \\\n#     libssl-dev \\\n#     \u0026\u0026 rm -rf /var/lib/apt/lists/*\n#\n# # Build steps\n# WORKDIR /usr/local/src\n# RUN ./configure --prefix=/usr/local \u0026\u0026 \\\n#     make\n#\n# # Install steps\n# RUN make install\n#\n# # Initialization steps\n# RUN mkdir -p /var/lib/nginx\n#\n# # Runtime configuration\n# EXPOSE 80\n# EXPOSE 443\n# USER nginx\n# WORKDIR /usr/local\n#\n# CMD [\"nginx\", \"-g\", \"daemon off;\"]\n```\n\n**Parameters:**\n\n- `plan_path`: Path to the Habitat plan.sh file\n- `base_image`: Docker base image (default: ubuntu:22.04). Validated for security\n\n**Features:**\n\n- **Dependency mapping**: Converts Habitat dependencies to apt packages\n- **Build optimization**: Multi-stage builds when applicable\n- **Security scanning**: Detects dangerous patterns (curl|sh, eval, etc.)\n- **Metadata preservation**: LABEL instructions for package info\n- **User configuration**: Non-root user setup when specified\n- **Port exposure**: Automatic EXPOSE directives from plan ports\n\n**Security Warnings:**\nThe 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.\n\n#### `generate_compose_from_habitat(plan_paths: str, network_name: str = \"habitat_net\")`\n\nGenerate docker-compose.yml from multiple Habitat plans for multi-service deployments.\n\n**Example:**\n\n```python\n# Single service\ngenerate_compose_from_habitat(\"/path/to/nginx/plan.sh\", \"myapp_network\")\n# Returns:\n# version: '3.8'\n# services:\n#   nginx:\n#     build:\n#       context: .\n#       dockerfile: Dockerfile.nginx\n#     container_name: nginx\n#     ports:\n#       - \"80:80\"\n#       - \"443:443\"\n#     environment:\n#       - HTTP=80\n#       - HTTPS=443\n#     networks:\n#       - myapp_network\n#\n# networks:\n#   myapp_network:\n#     driver: bridge\n\n# Multiple services with dependencies\ngenerate_compose_from_habitat(\n    \"/path/to/backend/plan.sh,/path/to/postgres/plan.sh\",\n    \"app_network\"\n)\n# Returns:\n# version: '3.8'\n# services:\n#   backend:\n#     build:\n#       context: .\n#       dockerfile: Dockerfile.backend\n#     container_name: backend\n#     ports:\n#       - \"8080:8080\"\n#     environment:\n#       - PORT=8080\n#     depends_on:\n#       - postgres\n#     networks:\n#       - app_network\n#\n#   postgres:\n#     build:\n#       context: .\n#       dockerfile: Dockerfile.postgres\n#     container_name: postgres\n#     ports:\n#       - \"5432:5432\"\n#     environment:\n#       - POSTGRESQL=5432\n#     volumes:\n#       - postgres_data:/var/lib/app\n#     networks:\n#       - app_network\n#\n# networks:\n#   app_network:\n#     driver: bridge\n#\n# volumes:\n#   postgres_data:\n```\n\n**Parameters:**\n\n- `plan_paths`: Comma-separated paths to plan.sh files for multiple services\n- `network_name`: Docker network name for service communication (default: habitat_net)\n\n**Features:**\n\n- **Multi-service orchestration**: Combines multiple Habitat plans into one compose file\n- **Automatic dependencies**: Creates depends_on from Habitat service binds\n- **Volume detection**: Identifies services needing persistent storage from do_init callbacks\n- **Network isolation**: Configures bridge networks for service communication\n- **Port management**: Maps ports from Habitat exports to Docker compose\n- **Environment variables**: Generates environment configuration from port definitions\n\n**Use Cases:**\n\n- Converting multi-service Habitat applications to Docker Compose\n- Creating development environments from production Habitat plans\n- Simplifying container orchestration for local testing\n- Migration path from Habitat to Kubernetes (via docker-compose)\n\n## Development\n\n### Project Structure\n\n```text\nsouschef/\n├── souschef/\n│   ├── __init__.py\n│   └── server.py          # MCP server implementation\n├── tests/\n│   ├── __init__.py\n│   └── test_server.py     # Comprehensive test suite\n├── .devcontainer/         # VS Code dev container config\n├── .github/\n│   └── copilot-instructions.md  # Copilot development guidelines\n├── pyproject.toml         # Project configuration\n└── README.md\n```\n\n### Development Standards\n\nSousChef uses a modern Python toolchain for code quality:\n\n- **Ruff**: Primary linter and formatter (replaces Black, isort, flake8)\n\n  ```bash\n  poetry run ruff check .    # Lint code\n  poetry run ruff format .   # Format code\n  ```\n\n- **mypy**: Static type checking for CI/CD\n\n  ```bash\n  poetry run mypy souschef   # Type check source code\n  ```\n\n- **Pylance**: Real-time VS Code type checking and intellisense\n  - Configured in `.vscode/settings.json`\n  - Provides immediate feedback during development\n\n- **pytest**: Testing framework with coverage reporting\n\n  ```bash\n  poetry run pytest --cov=souschef --cov-report=term-missing\n  ```\n\n**Quality Requirements:**\n\n- Zero warnings from all tools (Ruff, mypy, Pylance)\n- Type hints required for all functions\n- Google-style docstrings\n- 92% test coverage (exceeds 90% target)\n\nSee [.github/copilot-instructions.md](.github/copilot-instructions.md) for detailed development guidelines.\n\n### Running Tests\n\n```bash\n# Run all tests\npoetry run pytest\n\n# Run with coverage report\npoetry run pytest --cov=souschef --cov-report=term-missing --cov-report=html\n\n# Run specific test suites\npoetry run pytest tests/unit/test_server.py              # Core unit tests\npoetry run pytest tests/unit/test_cli.py                 # CLI tests\npoetry run pytest tests/e2e/test_mcp.py                  # MCP protocol tests\npoetry run pytest tests/integration/test_integration.py         # Integration tests\npoetry run pytest tests/integration/test_integration_accuracy.py # Accuracy validation\npoetry run pytest tests/unit/test_enhanced_guards.py     # Guard conversion tests\npoetry run pytest tests/unit/test_error_paths.py         # Error handling\npoetry run pytest tests/unit/test_error_recovery.py      # Error recovery\npoetry run pytest tests/integration/test_real_world_fixtures.py # Real-world cookbooks\npoetry run pytest tests/unit/test_property_based.py      # Hypothesis fuzz tests\npoetry run pytest tests/integration/test_performance.py         # Performance benchmarks\npoetry run pytest tests/unit/test_snapshots.py           # Snapshot regression tests\n\n# Run with benchmarks\npoetry run pytest --benchmark-only\n\n# Check code quality\npoetry run ruff check .        # Linting\npoetry run ruff format .       # Formatting\npoetry run mypy souschef       # Type checking\n```\n\n### Test Types\n\nThe project includes comprehensive test coverage across multiple dimensions:\n\n1. **Unit Tests** (`test_server.py`, `test_cli.py`, `test_mcp.py`)\n   - Mock-based tests for individual functions\n   - Test error handling and edge cases\n   - Fast execution, isolated from filesystem\n   - MCP protocol compliance testing\n\n2. **Integration Tests** (`test_integration.py`, `test_integration_accuracy.py`)\n   - Real file operations with test fixtures\n   - Validate parsing with actual Chef cookbook files\n   - Parameterized tests for various scenarios\n   - Accuracy validation for conversions\n\n3. **Property-Based Tests** (`test_property_based.py`)\n   - Uses Hypothesis for fuzz testing\n   - Generates random inputs to find edge cases\n   - Ensures functions handle any input gracefully\n\n4. **Specialized Test Suites**\n   - **Enhanced Guards** (`test_enhanced_guards.py`): Complex guard condition conversion\n   - **Error Handling** (`test_error_paths.py`, `test_error_recovery.py`): Comprehensive error scenarios\n   - **Real-World Fixtures** (`test_real_world_fixtures.py`): Production cookbook patterns\n   - **Performance** (`test_performance.py`): Benchmarking and optimization\n   - **Snapshots** (`test_snapshots.py`): Regression testing for output stability\n\n5. **Test Fixtures**\n  - Sample Chef cookbooks in `tests/integration/fixtures/`\n   - Multiple cookbook types: apache2, docker, mysql, nodejs, legacy Chef 12, Habitat plans\n   - Real-world metadata, recipes, attributes, and resources\n   - Used across integration and accuracy testing\n\n### Test Coverage\n\nThe project maintains 91% test coverage, exceeding the 90% target. Run coverage with HTML report:\n\n```bash\npoetry run pytest --cov=souschef --cov-report=html\nopen htmlcov/index.html  # View detailed coverage report\n```\n\n### Mutation Testing\n\nTo verify test quality with mutation testing:\n\n```bash\npoetry run mutmut run\npoetry run mutmut results\n```\n\n### VS Code Tasks\n\nThe project includes several VS Code tasks:\n\n- **Run Tests** - Execute test suite\n- **Run Tests with Coverage** - Generate coverage reports\n- **Lint (Ruff)** - Check code quality\n- **Format (Ruff)** - Auto-format code\n- **Lint \u0026 Test** - Run both linting and tests\n\n## Contributing\n\nThank you for your interest in contributing to SousChef!\n\n**Before you start**, please read the [**Architecture Guide**](docs/ARCHITECTURE.md) to understand where different code belongs and why. This is essential for understanding how to structure your contributions.\n\nFor complete contributing guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md), which includes:\n\n- Development setup instructions\n- Code standards and quality tools\n- Testing requirements and patterns\n- Commit conventions and PR process\n- Release procedures\n\n**Quick Checklist for Contributions:**\n\n1. Read [**docs/ARCHITECTURE.md**](docs/ARCHITECTURE.md) to understand module structure\n2. Ensure all tests pass: `poetry run pytest`\n3. Code passes linting: `poetry run ruff check .`\n4. Code is formatted: `poetry run ruff format .`\n5. Type hints are complete: `poetry run mypy souschef`\n6. Coverage maintained at 90%+\n7. All functions have docstrings\n8. Follow [conventional commits](CONTRIBUTING.md#commit-message-format)\n\nQuestions? Check [ARCHITECTURE.md](docs/ARCHITECTURE.md) for module responsibilities or [CONTRIBUTING.md](CONTRIBUTING.md) for the full developer guide.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkpeacocke%2Fsouschef","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkpeacocke%2Fsouschef","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkpeacocke%2Fsouschef/lists"}