Refactor cli.py and apm_package.py into focused modules (#172)

[sergio-sisternes-epam]

Description

Refactors the two largest source files into focused, maintainable modules. No user-facing behavior changes.

Fixes #172

Phase 1 — Extract CLI commands from cli.py into commands/

Reduced cli.py from 4,511 → 80 lines (thin wiring layer). Created 12 command modules:

Module	Lines	Contents
commands/_helpers.py	405	Shared utilities, console, lazy loaders
commands/init.py	192	init command + project setup
commands/install.py	1,449	install command + 936-line engine
commands/uninstall.py	556	uninstall + transitive cleanup
commands/prune.py	143	prune command
commands/update.py	136	update command
commands/compile.py	739	compile + watch mode
commands/run.py	218	run + preview commands
commands/list_cmd.py	110	list command
commands/config.py	169	config group (set/get)
commands/runtime.py	188	runtime group (setup/list/remove/status)
commands/mcp.py	373	mcp group (search/show/list)

Phase 2 — Split apm_package.py into focused model files

Reduced apm_package.py from 1,577 → 239 lines. Created 2 new modules:

Module	Lines	Contents
models/dependency.py	1,024	DependencyReference, ResolvedReference, GitReferenceType, MCPDependency, parse_git_reference
models/validation.py	388	ValidationResult, ValidationError, PackageType, PackageContentType, validate_apm_package + validators

Backward compatibility

• models/__init__.py re-exports all symbols
• apm_package.py includes re-exports for direct imports (from apm_cli.models.apm_package import X)
• Updated test patch paths to match new module locations

Type of change

• Bug fix
• New feature
• Documentation
• Maintenance / refactor

Testing

• Tested locally
• All existing tests pass (1,861 passed, 35 skipped, 2 pre-existing failures unrelated to this PR)
• No new test failures introduced

Verification

uv run python -c "from apm_cli.cli import cli; print('OK')"                    # No circular imports
uv run python -c "from apm_cli.models import DependencyReference, APMPackage, ValidationResult, ResolvedReference, PackageInfo; print('OK')"  # Re-exports intact
uv run apm --version && uv run apm --help                                       # CLI smoke test
uv run python -m pytest -q                                                      # Full test suite

[Copilot]

Pull request overview

Refactors the APM CLI and package model layers by splitting historically large modules into smaller, focused modules while maintaining backward-compatible imports and updating tests to point at the new module paths.

Changes:

• Extracted CLI commands into src/apm_cli/commands/* and reduced cli.py to a thin wiring layer.
• Split apm_package.py into models/dependency.py and models/validation.py, with re-exports preserved via models/__init__.py and models/apm_package.py.
• Updated unit/integration tests to patch/import functions from their new module locations.

Reviewed changes

Copilot reviewed 26 out of 28 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tests/unit/test_transitive_deps.py	Updates orphan-check helper import to new commands helpers module.
tests/unit/test_install_command.py	Updates patch paths to commands.install module.
tests/unit/test_canonicalization.py	Updates patch paths/imports for install canonicalization helper.
tests/unit/test_auth_scoping.py	Updates patch paths/imports for install validation helper.
tests/unit/integration/test_skill_integrator.py	Updates patch path for _rich_warning to utils.console.
tests/unit/compilation/test_compilation.py	Updates imports for compile validation display helpers.
tests/integration/test_version_notification.py	Updates patch path for update-check helper to commands._helpers.
tests/integration/test_selective_install_mcp.py	Updates patch paths to commands._helpers and commands.install.
tests/integration/test_generic_git_url_install.py	Updates patch paths/imports for install canonicalization helper.
src/apm_cli/models/validation.py	New module containing package validation logic and related enums/types.
src/apm_cli/models/dependency.py	New module containing dependency parsing/canonicalization/reference models.
src/apm_cli/models/apm_package.py	Slimmed core package dataclasses + re-exports for backward compatibility.
src/apm_cli/models/init.py	Centralized model re-exports updated to new module structure.
src/apm_cli/integration/skill_integrator.py	Updates warning helper import location to avoid CLI circular imports.
src/apm_cli/commands/_helpers.py	New shared helpers module (console/theme, YAML loaders, orphan detection, etc.).
src/apm_cli/commands/init.py	New init command module extracted from former CLI monolith.
src/apm_cli/commands/install.py	New install command module (not shown in excerpts) targeted by tests.
src/apm_cli/commands/uninstall.py	New uninstall command module with transitive cleanup + reintegration.
src/apm_cli/commands/prune.py	New prune command module using shared orphan-detection helpers.
src/apm_cli/commands/compile.py	New compile command module including watch/validate modes.
src/apm_cli/commands/run.py	New run + preview command module.
src/apm_cli/commands/list_cmd.py	New list command module for scripts display.
src/apm_cli/commands/config.py	New config group module, including invoke-without-command behavior.
src/apm_cli/commands/runtime.py	New runtime group module for runtime setup/list/remove/status.
src/apm_cli/commands/mcp.py	New mcp group module for registry browsing (search/show/list).
src/apm_cli/commands/update.py	New update command module to check/install latest CLI version.

---

You can also share your feedback on Copilot code review. Take the survey.