axm-doctor 0.2.0

axm-doctor — Environment detection and setup orchestration

Environment detection, install planning and credential setup orchestration for AXM. Python 3.12+; part of the axm-forge workspace.

Features

• Report installed tools, authentication states and missing credentials.
• Prepare install plans without executing them.
• Expose structured preflight through AXM tools and a human-readable CLI.
• Orchestrate confirmed setup through axm-vault without owning a secret store.

Installation

Requires Python 3.12 or newer. In a Python project managed by uv:

uv add axm-doctor

Quick Start

After installation, inspect the environment:

uv run axm-doctor check

check reports tools, third-party authentication, declaration provenance and missing credentials. It does not install or prompt. Normal reporting exits 0; --strict exits 1 for absent tools, logged_out auth or any missing credential, including optional ones. Operational errors also exit 1 without --strict.

Usage

Choose an interface

The AXM tools are discovered through axm.tools, exposed as axm env_doctor and axm auth_status, through MCP, and through tool_node. Successful report generation does not mean the machine is healthy; evaluate the returned states for your own preflight policy.

Install and inspect

Use uv run axm-doctor check --strict when the report should gate CI.

from axm_doctor import install_command, run_install

plan = install_command("uv")
assert plan is not None
print(plan.human_command)
result = run_install(plan)
assert not result.executed

Planning runs nothing. Installation requires run_install(plan, confirm=True). The built-in uv plan currently pins 0.8.4; a plan is not a latest-version lookup.

Boundaries

• Importing axm_doctor resolves exports lazily; detect_tool needs only stdlib and pydantic. Full reports also use axm-config and axm-vault.
• Authentication probes belong to installed credential declarations. Without a declaration, an installed binary is undetermined. A declared probe failure or timeout is currently logged_out; it is not proof of logout. detect_auth currently leaves login_cmd=None.
• Reports contain metadata, not credential values. Detection can launch subprocesses and invoke provider probes; read-only does not mean no I/O.
• Doctor owns no credential store. provision_missing() plans groups; confirmed execution delegates writes and prompts to vault. provide_secret() writes a value the caller already holds through vault without a TTY, and attests it by re-resolving the catalog rather than by the write returning.

Documentation

Getting started · Task guides · CLI · Python contracts · Architecture and limits

Published documentation.

The README is the repository entry point; docs/index.md is the site homepage.

Development

From the axm-forge workspace root:

uv sync --all-packages --all-groups
uv run --package axm-doctor --directory packages/axm-doctor pytest
uv run --package axm-doctor --directory packages/axm-doctor --group docs mkdocs build --strict

The package's configured test root is tests_axm_doctor/. Its standalone MkDocs build uses the documentation dependencies from the docs group.

License

Licensed under Apache-2.0. See LICENSE.