Add MOLECULE_SHARED_INVENTORY_DIR environment variable and playbook variable

Summary

Introduces MOLECULE_SHARED_INVENTORY_DIR as both an environment variable and playbook variable to enable access to shared inventory directories when using the --shared-inventory option. This enhancement allows scenarios to programmatically create and consume shared inventory files across multiple test runs.

Use Case

When testing complex multi-scenario setups, users often need to share inventory data between scenarios. The existing --shared-inventory option provides shared storage but lacks programmatic access from playbooks. This implementation enables:

• Dynamic inventory file creation in shared locations
• Cross-scenario inventory data consumption
• Custom inventory management workflows
• Enhanced testing of multi-service deployments

Implementation Details

Core Changes

Environment Variable (src/molecule/config.py)

• Added MOLECULE_SHARED_INVENTORY_DIR to environment variables
• Returns shared inventory path when --shared-inventory enabled and not in parallel mode
• Returns empty string in normal mode or parallel mode (where shared inventory is disabled)

Playbook Variable (src/molecule/provisioner/ansible.py)

• Added molecule_shared_inventory_dir to molecule variables available in all playbooks
• Uses environment lookup: {{ lookup('env', 'MOLECULE_SHARED_INVENTORY_DIR') }}
• Fixed inventory property type annotation from dict[str, str] to dict[str, Any]

Testing

Unit Tests

• tests/unit/test_config.py: Environment variable behavior across all modes
• tests/unit/provisioner/test_ansible.py: Playbook variable inclusion verification

Integration Tests

• tests/fixtures/integration/.../shared_inventory/: Complete test scenario with realistic inventory templating
• tests/integration/test_command.py: Dedicated test for shared inventory functionality

Documentation

Configuration Reference (docs/configuration.md)

• Documented new environment variable with usage context
• Referenced corresponding playbook variable availability

Usage Guide (docs/guides/sharing.md)

• Added practical examples showing inventory file creation and consumption
• Demonstrated real-world use cases with Jinja2 templating

Behavior

Example Usage

- name: Create shared inventory
  ansible.builtin.copy:
    content: "{{ inventory_ini }}"
    dest: "{{ molecule_shared_inventory_dir }}/shared_inventory.ini"
    mode: "0600"
  when: molecule_shared_inventory_dir != ""
  vars:
    inventory_ini: |
      [molecule]
      {% for platform in molecule_yml.platforms %}
      {{ platform.name }}{% for key, value in platform.get('host_vars', {}).items() %} {{ key }}={{ value }}{% endfor %}
      {% endfor %}
  delegate_to: localhost

Compatibility

• Fully backward compatible
• No changes to existing behavior
• New variables are additive only
• Follows established molecule variable patterns