refactor: Stage 1 strangler-fig -- extract mcp_integrator.py::install

[sergio-sisternes-epam]

Context

PR #999 introduced Ruff code quality guardrails with complexity thresholds set just above current codebase maximums (strangler-fig pattern). This is the first tightening stage.

Problem

src/apm_cli/integration/mcp_integrator.py::install is the single worst complexity outlier, owning three metrics simultaneously:

Metric	Current value	Stage 1 target	Final target
max-statements	282	200	50
max-complexity (McCabe)	104	80	30
max-branches	125	90	25

Refactoring this one method unlocks threshold reductions across all three metrics for the entire codebase.

Suggested approach

1. Extract distinct phases of the install method into private helper methods (e.g., _validate_inputs, _resolve_dependencies, _deploy_files, _run_hooks)
2. Each extracted method should be under 50 statements
3. After extraction, update the thresholds in pyproject.toml to the Stage 1 values
4. Run uv run ruff check src/ tests/ to confirm no new violations

Files to touch

• src/apm_cli/integration/mcp_integrator.py -- refactor install
• pyproject.toml -- tighten max-statements, max-complexity, max-branches

Full strangler-fig roadmap

From the simulation in #999:

Stage	max-stmts	max-complexity	max-branches	Files to fix
Current	300	110	130	0
Stage 1	200	80	90	8
Stage 2	100	40	50	34
Stage 3	75	25	30	58
Target	50	15	25	79

References

• Parent PR: feat: add Ruff code quality guardrails (replaces black + isort) #999
• Simulation methodology: described in feat: add Ruff code quality guardrails (replaces black + isort) #999 PR description

[github-actions]

Triage decision

accept

Proposed labels

area/cli
type/refactor
status/accepted
priority/low
good first issue

(No theme/* required -- this is a pure internal code quality refactor; only area/cli-class infrastructure is touched with no product surface implication.)

Milestone

0.9.4

Suggested next action

Open a draft PR against src/apm_cli/integration/mcp_integrator.py extracting the four helper methods described in the issue, confirm each is under 50 statements, tighten the three Ruff thresholds in pyproject.toml to the Stage 1 values (200 / 80 / 90), and run uv run ruff check src/ tests/ plus the unit suite before marking ready for review.

Suggested issue comment

Thanks for the well-structured refactor proposal, @sergio-sisternes-epam. The strangler-fig
roadmap from #999 is exactly the right incremental approach for a 282-statement,
104-complexity outlier like `mcp_integrator.py::install`.

This is accepted for the 0.9.4 patch milestone. The implementation path is clear:

1. Extract `_validate_inputs`, `_resolve_dependencies`, `_deploy_files`, and `_run_hooks`
   from `install`, keeping each helper under 50 statements.
2. Tighten `pyproject.toml` to the Stage 1 Ruff thresholds: `max-statements = 200`,
   `max-complexity = 80`, `max-branches = 90`.
3. Verify with `uv run ruff check src/ tests/` -- no new violations expected.
4. Run `uv run pytest tests/unit tests/test_console.py -x` to confirm no regressions.

A few things to keep in mind when picking this up:
- Each extracted helper should cover logic that is already tested or add a targeted unit
  test if the extracted path is currently uncovered.
- Keep extracted methods private (`_` prefix) -- no new public API surface should be needed.
- If the extraction reveals additional complexity (e.g., deeply shared state across phases),
  leave a comment in the PR and a maintainer can help scope the boundary.

This is marked `good first issue` because the approach is prescriptive and isolated to one
file. If you hit a snag, comment here and we will help scope the first extraction.

To get started, fork the repo and open a draft PR referencing this issue.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The request maps to a real developer-contributor surface: mcp_integrator.py::install at 282 statements, 104 McCabe complexity, and 125 branches is an extreme outlier that actively deters code contributions, reviews, and testing. The issue is aligned with APM's OSS contributor-friendliness mission. Framing is excellent -- specific metrics, concrete targets, a guided approach (extract four private helpers), and a staged roadmap inherited from #999. The good first issue tag is borderline given the raw complexity of the target method, but the prescriptive approach and staged nature mitigate the risk. No user-facing behavior changes; purely a maintainability improvement.

Supply Chain Security Expert -- Risk-Surface Reviewer

mcp_integrator.py::install is security-adjacent -- it drives file deployment, hook execution, and MCP config integration. However, the proposed change is a pure method extraction with no behavior change, no new API surface, and no new trust boundary. The residual risk is regression in existing security flows, mitigated by requiring tests alongside the refactor. No theme/security or theme/governance label is warranted: the issue does not introduce new attack surface, does not touch lockfile integrity, marketplace name resolution, signing, or auth. No risk-surface implication beyond standard regression testing discipline.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- author is COLLABORATOR with established interaction history on microsoft/apm; tone-tuning for first-time contributors is not warranted.

Python Architect -- Architecture Reviewer

Not activated -- the issue proposes a single-file method extraction within one class with no new interface, schema, data model, or cross-module contract decision required; the design is already specified prescriptively in the issue body.

Doc Writer -- Documentation Reviewer

Not activated -- this is a pure internal code quality refactor with no user-facing surface change and no new CLI flags, primitives, or authoring concepts; no documentation pages need to be added or updated.

APM CEO -- Triage Arbiter

This is a well-scoped, well-motivated code quality issue. Direction is unambiguous and the author has done the analytical work upfront. Decision: accept. No theme/* is required because this is a pure internal refactor touching only area/cli-class infrastructure with no product surface implication. Existing human labels (good first issue, tech-debt) are authoritative and preserved -- tech-debt is noted as a non-taxonomy label already on the issue; no action needed. The current patch milestone 0.9.4 is the right bucket for small DX/code-quality increments. Priority priority/low -- planned and useful, but not blocking any user-facing capability.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": null,
  "areas": ["area/cli"],
  "type": "type/refactor",
  "status": "status/accepted",
  "priority": "priority/low",
  "preserved_labels": ["good first issue"],
  "milestone": "0.9.4",
  "next_action": "Open a draft PR extracting the four helper methods from mcp_integrator.py::install, tighten pyproject.toml to Stage 1 Ruff thresholds (200/80/90), and run ruff check plus the unit suite before marking ready for review.",
  "comment_markdown": "Thanks for the well-structured refactor proposal, @sergio-sisternes-epam. The strangler-fig roadmap from #999 is exactly the right incremental approach for a 282-statement, 104-complexity outlier like `mcp_integrator.py::install`.\n\nThis is accepted for the 0.9.4 patch milestone. The implementation path is clear:\n\n1. Extract `_validate_inputs`, `_resolve_dependencies`, `_deploy_files`, and `_run_hooks` from `install`, keeping each helper under 50 statements.\n2. Tighten `pyproject.toml` to the Stage 1 Ruff thresholds: `max-statements = 200`, `max-complexity = 80`, `max-branches = 90`.\n3. Verify with `uv run ruff check src/ tests/` -- no new violations expected.\n4. Run `uv run pytest tests/unit tests/test_console.py -x` to confirm no regressions.\n\nA few things to keep in mind when picking this up:\n- Each extracted helper should cover logic that is already tested or add a targeted unit test if the extracted path is currently uncovered.\n- Keep extracted methods private (`_` prefix) -- no new public API surface should be needed.\n- If the extraction reveals additional complexity (e.g., deeply shared state across phases), leave a comment in the PR and a maintainer can help scope the boundary.\n\nThis is marked `good first issue` because the approach is prescriptive and isolated to one file. If you hit a snag, comment here and we will help scope the first extraction.\n\nTo get started, fork the repo and open a draft PR referencing this issue."
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel for issue #1004 · ● 746.9K · ◷