apm: Instructions file for GitHub Copilot

Integrator Architecture

Design philosophy

APM runs inside repositories of any size — from single-package repos to monorepos with thousands of packages and deep dependency trees. Every integrator must assume it will operate at that scale. The architecture is built around two principles:

1. One base, many file types. All file-level integrators share a single BaseIntegrator infrastructure for collision detection, manifest-based sync, path security, link resolution, and file discovery. New integrators add what to deploy, never how to deploy. When logic belongs to more than one integrator, push it into BaseIntegrator.
2. Pay only for what you touch. Operations must be proportional to the files a single package deploys, not the size of the workspace or the total managed-files set. Pre-normalize once, partition once, look up in O(1). Avoid full-tree walks, per-file parent cleanup, or repeated set scans.

When evolving integration logic -- new file types, richer transforms, cross-package awareness -- preserve these properties. If a change would violate either principle, refactor the base class first. This subsystem is the integration-specific instance of the repo-wide single-canonical-owner rule; see architecture.instructions.md.

Required structure

Every file-level integrator must extend BaseIntegrator and return IntegrationResult.

from apm_cli.integration.base_integrator import BaseIntegrator, IntegrationResult

class FooIntegrator(BaseIntegrator):
    def find_foo_files(self, package_path: Path) -> List[Path]: ...
    def copy_foo(self, source: Path, target: Path) -> int: ...
    def integrate_package_foos(self, package_info, project_root: Path,
                               force: bool = False,
                               managed_files: set = None) -> IntegrationResult: ...
    def sync_integration(self, apm_package, project_root: Path,
                         managed_files: set = None) -> Dict[str, int]: ...

Base-class methods — use, don't reimplement