Ansible/docs/DEVELOPMENT.md

AIM Development Guide

Project root

/etc/ansible/scripts/
├── pyproject.toml
└── src/
    └── aim/

The environment is installed editable:

/etc/ansible/.venv/bin/python -m pip install -e /etc/ansible/scripts

Architecture

Backend areas include inventory loading/writing/validation, customer management, backup/session recovery, locking, permissions, playbooks, SSH, Vault, Sophos and WinRM.

The 2.1 UI is split into focused modules under src/aim/ui/, including shared components, selection, execution, customers, hosts, access, playbooks, administration and target selection.

UI conventions

• Orange #ff7a00 is the AIM/bitformer accent.
• Green = success.
• Yellow = warning.
• Red = failure.
• No ASCII logo.
• Header identity: bitformer · AIM · Ansible Inventory Manager.
• Pagination: p / n.
• Numbered navigation: Enter/0 = Back or Cancel.
• Multi-select: number toggles; Enter reviews; 0 cancels.

Opening menus should not unexpectedly run Ansible, contact hosts, decrypt Vaults or prompt for passwords.

Inventory invariants

hosts.yml is authoritative. Preserve arbitrary valid YAML/custom keys/comments where possible.

Writes should be validated and atomic, with stale-write/concurrency protection and a session recovery backup.

Do not change unrelated Ansible connection/authentication parameters as part of feature work.

Packaging

Production packages should contain runtime source and metadata, without caches, .pyc, test artifacts, legacy Bash implementations or developer notes unless explicitly requested.

A release archive should expose pyproject.toml and src/ at its root rather than adding an extra wrapper directory.

Versioning

Use a patch release for contained fixes and a feature/minor release for larger functional changes. Update package metadata and the changelog together.