[FEATURE] Support global OpenCode MCP installation

[Christopher Lunt (tnulc)]

Adds global MCP installation support for OpenCode, including target paths, integration behavior, documentation, and tests.

[Christopher Lunt (tnulc)]

@microsoft-github-policy-service agree

[Copilot]

Copilot review overview

🟡 Changes recommended

Unresolved moderate issues affect OpenCode key handling, scope-aware cleanup, and custom-path cleanup.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1 · 8

Open (9)

• Honor legacy user_scope in stale OpenCode cleanup · New
• Add required PR number to changelog entry · New
• Add anchor for OPENCODE_CONFIG_DIR documentation · New
• Add anchor for OPENCODE_CONFIG_DIR documentation · New
• Add anchor for OPENCODE_CONFIG_DIR documentation · New
• Add anchor for OPENCODE_CONFIG_DIR documentation · New
• Update module docs for user-scope OpenCode configuration creation · New
• Include OpenCode in the no-runtime warning · New
• Register canonical OpenCode path ownership and lint guard · New

What changed in this PR

Adds global OpenCode MCP installation with configurable configuration paths, scope-aware integration, tests, and documentation.

Changes:

• Adds OPENCODE_CONFIG_DIR/XDG path resolution.
• Enables global OpenCode detection, writes, and cleanup.
• Updates tests, documentation, and changelog.

File	Summary	Final review notes
tests/​unit/​test_opencode_mcp.py	Tests path resolution and global writes.	No final comments.
tests/​unit/​test_global_mcp_scope.py	Updates scope expectations.	Nit (1 vote): Ensure OpenCode is tested with a present global config rather than filtered as workspace-only.
tests/​unit/​integration/​test_targets.py	Tests global target resolution.	No final comments.
src/​apm_cli/​integration/​targets.py	Resolves configurable OpenCode roots.	Moderate (1 vote): Use the canonical user-root helper for fallback prefixes so custom paths are cleaned up correctly.
src/​apm_cli/​integration/​opencode_paths.py	Defines path precedence.	Nit (3 votes): Register the module as the canonical owner and add the required static guard.
src/​apm_cli/​integration/​mcp_integrator.py	Handles scope-aware cleanup.	Moderate (3 votes): Derive effective user scope from both legacy and new parameters, with explicit project scope taking precedence.
src/​apm_cli/​integration/​mcp_integrator_install.py	Detects global OpenCode configuration.	Nit (2 votes): Include OpenCode in the no-runtime warning’s supported list.
src/​apm_cli/​adapters/​client/​opencode.py	Supports global MCP writes.	Moderate (1 vote): Set mcp_servers_key to mcp for conflict and ownership handling. Nit (4 votes): Update the stale module documentation about user-scope directory creation.
docs/​src/​content/​docs/​reference/​targets-matrix.md	Documents OpenCode targets.	Nit (2 votes): Fix the unresolved opencode_config_dir fragment link.
docs/​src/​content/​docs/​reference/​environment-variables.md	Documents environment variables.	Nits (1 vote each): Add the missing anchor and correct the OPENCODE_CONFIG_DIR/XDG auto-detection descriptions.
docs/​src/​content/​docs/​reference/​cli/​install.md	Documents global installation.	Nits (2, 1 votes): Fix the unresolved environment-variable fragment and update stale packaged skill guidance.
docs/​src/​content/​docs/​reference/​cli/​compile.md	Documents global compilation.	Nit (2 votes): Fix the unresolved opencode_config_dir fragment link.
docs/​src/​content/​docs/​producer/​compile.md	Updates compile destinations.	Nit (2 votes): Fix the unresolved opencode_config_dir fragment link.
docs/​src/​content/​docs/​integrations/​ide-tool-integration.md	Documents MCP config paths.	No final comments.
docs/​src/​content/​docs/​consumer/​install-mcp-servers.md	Updates the MCP target matrix.	No final comments.
docs/​src/​content/​docs/​concepts/​primitives-and-targets.md	Updates target overview.	No final comments.
CHANGELOG.md	Records the feature.	Nit (4 votes): Add the required PR-number suffix to the Unreleased entry.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟡 Changes recommended

It introduces a no-scope Copilot cleanup regression, a Windows-incompatible test assertion, and stale bundled usage guidance.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1 · 1 · 1

Open (3)

• Preserve legacy Copilot cleanup when scope is unspecified · New
• Guard POSIX mode assertion for Windows portability · New
• Update APM usage guidance for new OpenCode config path behavior · New

Resolved since last review (9)

• Honor legacy user_scope in stale OpenCode cleanup
• Register canonical OpenCode path ownership and lint guard
• Include OpenCode in the no-runtime warning
• Update module docs for user-scope OpenCode configuration creation
• Add anchor for OPENCODE_CONFIG_DIR documentation
• Add anchor for OPENCODE_CONFIG_DIR documentation
• Add anchor for OPENCODE_CONFIG_DIR documentation
• Add anchor for OPENCODE_CONFIG_DIR documentation
• Add required PR number to changelog entry

[Copilot]

Copilot review overview

🟡 Changes recommended

Legacy scope handling can modify global Claude configuration unexpectedly, and the documentation and tests contain inconsistencies.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Require explicit user scope before cleaning Claude's global file · New
• Update documentation to consistently describe OpenCode user scope · New

Resolved since last review (3)

• Preserve legacy Copilot cleanup when scope is unspecified
• Guard POSIX mode assertion for Windows portability
• Update APM usage guidance for new OpenCode config path behavior

Previously missed (1)

In code that hasn't changed since last review

Isolate Path.home in target discovery test

tests/​unit/​integration/​test_targets.py:112

active_targets_user_scope() also scans every target directory under the real Path.home(). On a developer or runner that already has another supported client configured, this exact-list assertion returns additional targets and becomes machine-dependent. Patch Path.home to the test's temporary root before discovery.

This issue also appears on line 114 of the same file.

[Christopher Lunt (tnulc)]

Also fixed the Copilot test-isolation finding in 2407ac1: OpenCode user-scope discovery tests now patch Path.home() to their temporary root.

[Copilot]

Copilot review overview

🟡 Changes recommended

The adapter schema registry test will fail for the new mcp key, and the new canonical path owner lacks required architecture guardrails.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Add mcp to recognized adapter schema keys · New
• Verify cleanup targets isolated user config path · New

Resolved since last review (2)

• Require explicit user scope before cleaning Claude's global file
• Update documentation to consistently describe OpenCode user scope

[Copilot]

Copilot review overview

🟡 Changes recommended

Configured-root symlinks remain traversable, Windows external roots can evade cleanup, and the new path authority lacks required architecture guardrails.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1 · 1 · 2

Open (4)

• Check boundary symlinks before excluding the boundary path · New
• Normalize Windows override roots to prevent orphaned OpenCode files · New
• Document user-scope commands in the environment-variable contract · New
• Skip symlink tests when creation is unsupported · New

Resolved since last review (2)

• Add mcp to recognized adapter schema keys
• Verify cleanup targets isolated user config path

[Christopher Lunt (tnulc)]

Addressed the remaining global OpenCode lifecycle issues in 75aa5bed9:

• preserve user scope for files inside globally deployed OpenCode skill bundles;
• clean only the removed target-relative locator when targets share a compatibility path;
• keep the surviving manifest/hash entry for that shared path.

Validated with:
.venv/bin/python -m pytest tests/unit/test_global_mcp_scope.py tests/unit/test_opencode_mcp.py tests/unit/integration/test_targets.py tests/unit/install/test_services.py tests/unit/install/phases/test_lockfile_union.py -q

Result: 217 passed.

---

Generated by receiving-code-review. This comment is AI-generated and may contain errors.

[Copilot]

Copilot review overview

🟡 Changes recommended

Symlink validation and target-relative cleanup still have security and ownership correctness gaps.

Review effort: Balanced
Findings: 1

Open (1)

• Cleanup outcomes lose target identity when locators share paths · New

Resolved since last review (1)

• Validate all lexical config path components before normalization

Previously missed (2)

In code that hasn't changed since last review

Locator grouping is duplicated instead of centralized

src/​apm_cli/​install/​manifest_reconcile.py:60

This duplicates the locator-grouping decision in install/phases/cleanup.py:38-44. Move the grouping behavior to the canonical deployment-ledger owner and call it from both reconciliation paths so fixes to composite locator handling cannot diverge.

Duplicate locator grouping implementations can diverge

src/​apm_cli/​install/​phases/​cleanup.py:44

This introduces a second implementation of locator grouping; install/manifest_reconcile.py:54-60 contains the same decision. Because cleanup correctness depends on preserving every composite locator sharing a compatibility value, centralize this operation on the deployment-ledger owner and have both callers use it rather than allowing the two copies to drift.

[Christopher Lunt (tnulc)]

Addressed the follow-up symlink-validation and target-relative ownership findings in 3d37ab325:

• preserve lexical OpenCode roots for symlink checks while retaining resolved paths where containment needs them;
• reject symlinked user roots before global deployment or MCP cleanup;
• resolve target-relative cleanup through persisted target profiles, including custom external OpenCode roots;
• preserve locator identity for deleted and retained cleanup outcomes so same-valued paths cannot affect another target's ledger record;
• retain legacy compatibility projections and Claude custom-config cleanup behavior.

Validated with:
.venv/bin/python -m pytest tests/unit/cache/test_cleanup.py tests/unit/install/test_manifest_reconcile_target_relative.py tests/unit/test_target_env_roots.py tests/unit/test_opencode_mcp.py tests/unit/test_mcp_integrator_remove_stale.py tests/unit/integration/test_cleanup_helper.py tests/unit/integration/test_targets.py tests/unit/install/phases/test_lockfile_union.py tests/integration/test_mcp_integrator_characterisation.py -q

Result: 286 passed.

---

Generated by receiving-code-review. This comment is AI-generated and may contain errors.

[Christopher Lunt (tnulc)]

Follow-up fix pushed in 7feaaa800 for the mixed cleanup outcome case:

• deleted and user-edited locators with the same compatibility value now retain outcomes by DeploymentLocator.key;
• value-based legacy retention is used only for records with no identity outcome;
• the deleted target is no longer restored when another target's file is user-edited.

Validated with:
.venv/bin/python -m pytest tests/unit/install/test_manifest_reconcile_target_relative.py tests/unit/install/phases/test_lockfile_union.py tests/unit/integration/test_cleanup_helper.py -q

Result: 69 passed.

---

Generated by receiving-code-review. This comment is AI-generated and may contain errors.

[Copilot]

Copilot review overview

🟡 Changes recommended

External-root validation and cleanup contain correctness and symlink-safety gaps, and several tests remain non-portable.

Review effort: Balanced
Findings: 1 · 2 · 1

Open (4)

• Allow absolute user roots outside project_root · New
• Remove deleted locators from deferred cleanup tracking · New
• Recognize target-relative two-component skill directories · New
• Skip symlink test when creation is unavailable · New

Resolved since last review (1)

• Cleanup outcomes lose target identity when locators share paths

[Christopher Lunt (tnulc)]

Addressed the four follow-up review comments in e34608955:

• allow supported absolute external OpenCode roots while retaining lexical symlink rejection;
• finalize deferred skill-directory cleanup outcomes instead of retaining deleted locators;
• accept target-relative skills/<name> directory locators;
• make target-root symlink tests skip cleanly when directory symlinks are unavailable.

Validated with:
.venv/bin/python -m pytest tests/unit/test_target_env_roots.py tests/unit/integration/test_cleanup_skill_dirs.py tests/unit/integration/test_cleanup_helper.py tests/unit/install/test_manifest_reconcile_target_relative.py tests/unit/integration/test_targets.py tests/integration/test_target_resolution_e2e.py -q

Result: 180 passed, 2 xfailed.

---

Generated by receiving-code-review. This comment is AI-generated and may contain errors.

[Christopher Lunt (tnulc)]

The current head e34608955 contains the requested runtime fixes:

• absolute external user roots are accepted after lexical symlink validation;
• deferred skill-directory entries are finalized only as deleted/retained outcomes;
• target-relative skills/<name> directories are recognized and cleaned safely.

These comments remain open in GitHub despite the fixes being present in the current diff. Focused validation passed: 180 passed, 2 xfailed.

[Christopher Lunt (tnulc)]

Added the canonical-owner architecture guard in efc54f1a6:

• registered opencode_paths.py as the owner of OpenCode config-root precedence and lexical/resolved path identity;
• added a static guard rejecting direct OPENCODE_CONFIG_DIR/XDG_CONFIG_HOME reads and duplicated default-path resolution outside the owner;
• registered the guard and added owner-rule mutation plus rule-inventory coverage.

Ruff and Ruff format pre-commit hooks passed, and git diff --check passed. The architecture boundary script reports only the two pre-existing baseline findings in deployment_ledger.py and manifest_reconcile.py; focused pytest could not run in the clean checkout because its pyenv environment has no pytest executable.

---

Generated by receiving-code-review. This comment is AI-generated and may contain errors.

[Copilot]

Copilot review overview

🟡 Changes recommended

Multi-target locator identity, cleanup ownership filtering, and symlink-boundary handling remain unsafe.

Review effort: Balanced
Findings: 2 · 1

Open (3)

• Filter cleanup locators by package ownership · New
• Validate symlink components consistently for all external roots · New
• Handle unsupported symlinks and skip the regression test · New

Resolved since last review (4)

• Allow absolute user roots outside project_root
• Recognize target-relative two-component skill directories
• Remove deleted locators from deferred cleanup tracking
• Skip symlink test when creation is unavailable

Previously missed (1)

In code that hasn't changed since last review

Remove unreachable duplicate Claude project condition

src/​apm_cli/​install/​deployed_paths.py:72

This second Claude/project condition is unreachable: the identical condition immediately above always either returns or continues. Remove the dead branch so the absolute-root projection has one clear implementation.

[Christopher Lunt (tnulc)]

Implemented the remaining canonical-owner architecture follow-up in efc54f1:\n\n- registered src/apm_cli/integration/opencode_paths.py in the architecture owner registry;\n- added a static guard preventing consumers from duplicating OpenCode environment/default path resolution;\n- registered the guard and added mutation plus rule-inventory coverage.\n\nRuff hooks and git diff --check passed. The architecture linter reports only the two pre-existing baseline findings in deployment_ledger.py and manifest_reconcile.py. Focused pytest was unavailable in the clean checkout because its pyenv environment has no pytest executable.\n\n---\n\nGenerated by receiving-code-review. This comment is AI-generated and may contain errors.

[Christopher Lunt (tnulc)]

Addressed the three latest open review comments in 5621eb483:

• filter cleanup locator mappings by the package being cleaned, preventing cross-package deletion when compatibility paths collide;
• apply bounded lexical symlink-component validation to absolute external roots, matching MCP and primitive deployment safety;
• skip symlink setup tests on both OSError and NotImplementedError.

Validation: 118 focused tests passed; Ruff, Ruff format, and git diff --check passed.

[Copilot]

Copilot review overview

🟡 Changes recommended

External-root hashing, locator identity, and nested symlink checks remain unsafe or incomplete.

Review effort: Balanced
Findings: 2

Open (2)

• Resolve target-relative paths through owning profile before hashing · New
• Include every configured root component in symlink checks · New

Resolved since last review (3)

• Validate symlink components consistently for all external roots
• Filter cleanup locators by package ownership
• Handle unsupported symlinks and skip the regression test

Previously missed (1)

In code that hasn't changed since last review

Skip symlink test when filesystem lacks symlink support

tests/​unit/​test_opencode_mcp.py:76

This unguarded symlink creation fails on Windows or restricted filesystems before the behavior can be tested. The repository convention is to catch OSError/NotImplementedError and skip when symlinks are unavailable (for example, tests/unit/marketplace/test_builder.py:2061-2064).

[Christopher Lunt (tnulc)]

The work from this PR has been split into two replacement PRs:

• OpenCode MCP lexical symlink safety: fix(opencode): close lexical MCP root gap #3098
• External-root target-relative hashing/provenance: fix(install): hash external target-relative files #3097

Closing this umbrella PR so the two focused PRs can proceed independently.