Summary

Adds a schema-driven Python API (V1 class in ansible_creator.api) for programmatic interaction with ansible-creator, intended for internal Ansible ecosystem tooling (ansible-dev-tools server, VS Code extension, MCP servers). Also adds a schema CLI subcommand and supporting documentation.

V1 API

• Dynamic command discovery via argparse introspection -- no maintenance required when new subcommands are added
• schema() / schema_for() for capability introspection
• run(*command_path, **kwargs) constructs argv and feeds real argparse for validation and dispatch
• build_command(*command_path, **kwargs) returns the constructed argv without executing
• CreatorResult dataclass with status, path, logs, and message
• Output capture via captured_messages parameter on Output class
• Explicit path support (init_path/path) or auto temporary directory for init/add
• CLI output options (log_file, verbose, json, etc.) supported through argv construction
• Routing key conflict detection and unknown kwarg validation
• Proper action="count" handling (verbose=2 produces -v -v)

Architecture

• ansible_creator.schema -- root-level module for schema introspection; subcommands/schema.py is a thin CLI wrapper
• Parser.build_parser() -- shared parser tree construction used by CLI, Schema, and API
• Helper extractions (_build_output, _walk_to_leaf, _action_to_argv) keep method complexity under linter thresholds

Additional changes

• Normalized add resource ai subparser to accept a path positional and --overwrite/--no-overwrite flags, matching all other resource subparsers
• Output.critical() in capture mode now routes through self.log() for consistent file logging
• docs/api.md documents the internal API

Relates: https://issues.redhat.com/browse/AAP-62949

Test plan

• 47 unit tests in test_api.py covering build_command, schema, init, add, error handling, verbosity, output capture, explicit paths, count actions, and unknown kwargs
• Full unit test suite passes
• Pre-commit passes (ruff, mypy, pydoclint, pylint, cspell, markdownlint, ansible-lint)

Made with Cursor