feat: add --global / -g flag for scoped package installation

[Copilot]

Description

APM currently installs all packages at project scope with no way to install to user-level directories. This adds --global / -g to apm install and apm uninstall, mirroring npm's -g semantics.

User-scope stores metadata under ~/.apm/ (manifest, lockfile, modules) and deploys primitives to user-level directories where supported. Currently, only Claude Code natively reads from ~/.claude/ at user level. Copilot, Cursor, and OpenCode do not support user-level primitives via the filesystem — APM warns about this during --global installs.

# Install to user scope (available across all projects)
apm install -g microsoft/apm-sample-package

# Remove from user scope
apm uninstall -g microsoft/apm-sample-package

Core changes:

• New src/apm_cli/core/scope.py — InstallScope enum, path resolution helpers (get_deploy_root, get_apm_dir, get_modules_dir, get_manifest_path), USER_SCOPE_TARGETS registry with per-target support status, primitives list, and reference URLs to official documentation
• apm install — --global flag wired through to _install_apm_dependencies(), scope-aware manifest/lockfile/modules paths, warning emitted for targets without native user-scope support
• apm uninstall — --global flag with scope-aware paths for all cleanup steps
• _create_minimal_apm_yml / _validate_and_add_packages_to_apm_yml — accept optional target/manifest path for non-CWD manifests (needed because global scope writes to ~/.apm/apm.yml)
• warn_unsupported_user_scope() / get_unsupported_targets() — helpers that report which targets lack native user-level config support
• New docs/src/content/docs/guides/scoped-installation.md — per-target support table with status, primitives at user scope, and reference links to each tool's documentation

Type of change

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

Testing

• Tested locally
• All existing tests pass
• Added tests for new functionality (if applicable)

26 tests in tests/unit/core/test_scope.py (enum, path resolution, ensure_user_dirs, target registry support flags, unsupported target warnings). 4 tests in tests/unit/test_install_command.py (--global flag behavior with warning output, -g short flag, user manifest creation, error handling). 17 integration tests in tests/integration/test_global_scope_e2e.py covering cross-platform scenarios: directory creation under ~/.apm/, CLI output/warnings, error handling, manifest placement (auto-bootstrap, no CWD pollution, lockfile location), cross-platform path resolution (absolute paths, POSIX format, tilde prefixes), and uninstall lifecycle (package removal from manifest, not-found warnings). Tests use subprocess-based CLI invocation with isolated HOME/USERPROFILE directories. All 3059 tests pass. CodeQL: 0 alerts.

Original prompt

In popular package manager, you have the option to install packages at local or global scopes (-g, --global). Currently, APM has no explicit way to set the scope of the installation. We need to study and create an issue to propose how we could scope APM installation packages.

Examples:

• A package installed at vscode project level
• A package installed at vscode user settings level
• A package installed at copilot project level
• A package installed at copilot global level

We should explore alternatives for all existing supported platforms and AI providers in the project

Custom agent used: python-architect
Expert on Python design patterns, modularization, and scalable architecture for the APM CLI codebase. Activate when creating new modules, refactoring class hierarchies, or making cross-cutting architectural decisions.

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

[sergio-sisternes-epam]

We should add also the scope of global primitives.
We need to confirm all targets are supported. If not supported, a gap should be logged on the table and a warning should be traced during installation

[Copilot]

Updated in 144c9fa. The per-target support table now shows status (Supported / Not supported / Unverified), which primitives work at user scope per target, and reference links to each tool's documentation. Only Claude Code is verified as supported. APM now also shows a [!] warning during apm install --global listing the targets that lack native user-level support.

[sergio-sisternes-epam]

@copilot Review my comments. If I posted a question just answer it. If I want a code change I'll ask

[Copilot]

@copilot Review my comments. If I posted a question just answer it. If I want a code change I'll ask

Understood. I'll only answer questions going forward and wait for explicit requests before making code changes.

[sergio-sisternes-epam]

@copilot we need to consider including some integration tests to cover the new global feature. This is especially important, given we are supporting multiple operating systems

[Copilot]

Pull request overview

Adds a user-level installation scope to APM so packages can be installed/uninstalled globally (metadata under ~/.apm/) while keeping existing project-scope behavior unchanged.

Changes:

• Introduces InstallScope + scope-aware path helpers and user-scope target support/warning helpers.
• Wires -g/--global through apm install and apm uninstall, including scoped manifest/lockfile/modules handling.
• Adds unit tests and documentation for scoped installation behavior, plus changelog entries.

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/apm_cli/core/scope.py	New scope abstraction (project vs user), path resolution helpers, and unsupported-target warning helpers.
src/apm_cli/commands/install.py	Adds -g/--global, uses scope-aware manifest/modules/lockfile paths, and passes scope into the install engine.
src/apm_cli/commands/uninstall/cli.py	Adds -g/--global and uses scope-aware manifest/modules/lockfile paths and deploy root for cleanup.
src/apm_cli/commands/_helpers.py	Allows writing a minimal manifest to an explicit path (needed for ~/.apm/apm.yml).
tests/unit/core/test_scope.py	New unit tests for InstallScope, path helpers, dir creation, and warnings.
tests/unit/test_install_command.py	New tests for apm install -g/--global behavior and manifest creation.
docs/src/content/docs/guides/scoped-installation.md	New guide explaining project vs user scope and per-target support.
docs/src/content/docs/reference/cli-commands.md	Documents -g/--global for install/uninstall and adds examples.
CHANGELOG.md	Adds Unreleased entries describing the new global scope feature.

Comments suppressed due to low confidence (1)

src/apm_cli/commands/install.py:615

• The verbose log line still says Parsed apm.yml even when running with --global and parsing ~/.apm/apm.yml. This makes --verbose output misleading in user scope. Consider using manifest_display (or the resolved manifest_path) in this message so the output reflects the actual file being parsed.

        logger.verbose_detail(
            f"Parsed {APM_YML_FILENAME}: {len(apm_package.get_apm_dependencies())} APM deps, "
            f"{len(apm_package.get_mcp_dependencies())} MCP deps"
            + (f", {len(apm_package.get_dev_apm_dependencies())} dev deps"
               if apm_package.get_dev_apm_dependencies() else "")
        )

[Copilot]

This test verifies that ~/.apm/apm.yml is created, but it never asserts result.exit_code == 0 (or inspects result.exception). Adding an exit-code assertion would ensure the command completed successfully and prevent false positives where the manifest is created but the command later fails.

Suggested change

	assert result.exit_code == 0

[Copilot]

The new Unreleased changelog entries don't follow the existing file's convention of ending each bullet with a PR reference like (#NNN) (see other entries below). Also, these three bullets read like one logical change and could be consolidated into a single concise entry with the PR number appended for consistency.

Suggested change

	- `apm install --global` / `-g` flag for user-scope package installation; deploys primitives to `~/.github/`, `~/.claude/`, etc. and tracks metadata under `~/.apm/`
	- `apm uninstall --global` / `-g` flag for removing user-scope packages
	- `InstallScope` enum and scope resolution module (`core/scope.py`) defining project vs user deployment paths
	- Global `apm install --global` / `-g` and `apm uninstall --global` flags for user-scope package installation, backed by `InstallScope`-based scope resolution in `core/scope.py`; deploys primitives to `~/.github/`, `~/.claude/`, etc. and tracks metadata under `~/.apm/` (#440)

[Copilot]

In the new user-scope flow, several operations (importing scope helpers, ensure_user_dirs(), warn_unsupported_user_scope()) run before logger is instantiated, but the surrounding except Exception block later calls logger.error(...). If an exception is raised before logger is assigned, this will trigger an UnboundLocalError and mask the original failure. Create the InstallLogger before any scope initialization (or guard the exception handler to fall back to _rich_error when logger is not available).

[Copilot]

For apm uninstall -g, the missing-manifest message suggests running apm init first. apm init creates a project-scope ./apm.yml, so this guidance is incorrect for user scope. Consider branching the message by scope (e.g., instruct to create ~/.apm/apm.yml or run an apm install -g <pkg> bootstrap) while keeping the current apm init suggestion for project scope.

Suggested change

	logger.error(f"No {manifest_path} found. Run 'apm init' first.")
	if scope is InstallScope.USER:
	logger.error(
	"No user manifest found at ~/.apm/apm.yml. Install a package globally "
	"first with 'apm install -g <package>' or create the file manually."
	)
	else:
	logger.error(f"No {manifest_path} found. Run 'apm init' in this project first.")

[Copilot]

The new --global install test asserts on output content but does not assert the expected exit code. Adding an assert result.exit_code == 1 here (since no manifest/packages are provided) would make the test stricter and avoid passing if the command unexpectedly succeeds/fails in a different way.

[Copilot]

@copilot we need to consider including some integration tests to cover the new global feature. This is especially important, given we are supporting multiple operating systems

Added 17 integration tests in tests/integration/test_global_scope_e2e.py (7486d4b). Tests use subprocess-based CLI invocation with isolated HOME directories (overriding HOME and USERPROFILE on Windows) to cover:

• Directory creation: ~/.apm/ and ~/.apm/apm_modules/ via --global and -g
• CLI output: user scope info message, unsupported target warnings for both install and uninstall
• Error handling: missing manifest without packages, missing manifest on uninstall
• Manifest placement: auto-bootstrap to ~/.apm/apm.yml, no CWD pollution, lockfile location
• Cross-platform paths: absolute path validation, POSIX path format, tilde-prefixed user roots
• Uninstall lifecycle: package removal from user manifest, not-found warnings

All tests pass on Linux. The HOME/USERPROFILE override pattern matches existing integration tests (test_golden_scenario_e2e.py, test_auto_install_e2e.py) and will work on Windows CI as well.