apm-cli 0.16.1__tar.gz → 0.18.0__tar.gz

{apm_cli-0.16.1/src/apm_cli.egg-info → apm_cli-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: apm-cli
-Version: 0.16.1
+Version: 0.18.0
 Summary: MCP configuration tool
 Author-email: Daniel Meppiel <user@example.com>
 License: MIT License

{apm_cli-0.16.1 → apm_cli-0.18.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "apm-cli"
-version = "0.16.1"
+version = "0.18.0"
 description = "MCP configuration tool"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -88,21 +88,22 @@ ignore = [
     "S602",     # subprocess-popen-with-shell -- intentional in CLI wrapping git/pip
     # --- Deferred rules: enable in dedicated future PRs ---
     "SIM102",   # collapsible-if -- 28 violations, auto-fixable style improvement
-    "RUF003",   # ambiguous-unicode-character-comment -- 14 violations, review against ASCII convention
-    "RUF002",   # ambiguous-unicode-character-docstring -- 8 violations, same as above
 ]
 
 [tool.ruff.lint.pylint]
 # High initial thresholds set just above current codebase maximums.
 # Prevents new code from exceeding the worst existing violations.
 # Tighten these over time via dedicated refactoring PRs.
-max-statements = 275   # current max: 269 (mcp_integrator.py::install)
-max-args = 18          # current max: 16  (commands/install.py)
-max-branches = 115     # current max: 108 (mcp_integrator.py::install)
-max-returns = 18       # current max: 16  (marketplace/publisher.py)
+# Stage 1 thresholds (PR #1464, issue #1077).
+# Roadmap: Stage 2 targets max-complexity<=20, max-branches<=25 (McCabe standard).
+max-statements = 200   # Stage 1 (was 275)
+max-args = 15          # Stage 1 (was 18)
+max-branches = 60      # Stage 1 (was 115)
+max-returns = 12       # Stage 1 (was 18)
 
 [tool.ruff.lint.mccabe]
-max-complexity = 100   # current max: 97  (mcp_integrator.py::install)
+# Stage 1 (was 100). Stage 2 target: <=20 (McCabe industry standard).
+max-complexity = 50
 
 [tool.ruff.lint.per-file-ignores]
 # Subprocess calls are intentional in a CLI tool
@@ -120,7 +121,6 @@ max-complexity = 100   # current max: 97  (mcp_integrator.py::install)
 "src/apm_cli/commands/init.py" = ["F821", "S603", "S607"]
 "src/apm_cli/install/pipeline.py" = ["F821", "S603", "S607"]
 "src/apm_cli/integration/skill_integrator.py" = ["F821", "S603", "S607"]
-
 [tool.ruff.format]
 quote-style = "double"
 indent-style = "space"

{apm_cli-0.16.1 → apm_cli-0.18.0}/src/apm_cli/adapters/client/base.py

@@ -150,6 +150,21 @@ class MCPClientAdapter(ABC):
         self._last_env_placeholder_keys: set[str] = set()
         self._last_legacy_angle_vars: set[str] = set()
 
+    def _format_runtime_env_placeholder(self, name: str) -> str:
+        """Return the target runtime's env-var placeholder syntax for *name*."""
+        return "${" + name + "}"
+
+    def _translate_env_placeholder_for_runtime(self, value):
+        """Translate env-var placeholders to this adapter's runtime syntax."""
+        if not isinstance(value, str):
+            return value
+
+        def _to_runtime(match):
+            var_name = match.group(1) or match.group(2)
+            return self._format_runtime_env_placeholder(var_name)
+
+        return _ENV_PLACEHOLDER_RE.sub(_to_runtime, value)
+
     @property
     def project_root(self) -> Path:
         """Return the explicit project root or the current working directory."""
@@ -390,9 +405,7 @@ class MCPClientAdapter(ABC):
                     continue
                 if _has_env_placeholder(raw_value):
                     self._last_legacy_angle_vars.update(_extract_legacy_angle_vars(raw_value))
-                    translated[name] = _translate_env_placeholder(raw_value)
-                    # Record every ${VAR} in the translated value (handles
-                    # both ${env:VAR} -> ${VAR} and bare ${VAR} cases).
+                    translated[name] = self._translate_env_placeholder_for_runtime(raw_value)
                     placeholder_keys.extend(
                         m.group(1) for m in _ENV_VAR_RE.finditer(translated[name])
                     )
@@ -403,7 +416,7 @@ class MCPClientAdapter(ABC):
                 else:
                     # Literal value present in apm.yml -- replace with a
                     # runtime placeholder so the secret never touches disk.
-                    translated[name] = "${" + name + "}"
+                    translated[name] = self._format_runtime_env_placeholder(name)
                     placeholder_keys.append(name)
             self._last_env_placeholder_keys = set(placeholder_keys)
             return translated
@@ -421,7 +434,7 @@ class MCPClientAdapter(ABC):
                 if name in self._DEFAULT_GITHUB_ENV:
                     resolved[name] = self._DEFAULT_GITHUB_ENV[name]
                 else:
-                    resolved[name] = "${" + name + "}"
+                    resolved[name] = self._format_runtime_env_placeholder(name)
                     placeholder_keys.append(name)
             self._last_env_placeholder_keys = set(placeholder_keys)
             return resolved
@@ -510,7 +523,7 @@ class MCPClientAdapter(ABC):
             self._last_env_placeholder_keys.update(legacy_keys)
             for match in _ENV_VAR_RE.finditer(value):
                 self._last_env_placeholder_keys.add(match.group(1))
-            return _translate_env_placeholder(value)
+            return self._translate_env_placeholder_for_runtime(value)
 
         from rich.prompt import Prompt
 
@@ -560,7 +573,7 @@ class MCPClientAdapter(ABC):
 
         if self._supports_runtime_env_substitution:
             self._last_legacy_angle_vars.update(_extract_legacy_angle_vars(processed))
-            processed = _translate_env_placeholder(processed)
+            processed = self._translate_env_placeholder_for_runtime(processed)
         else:
             # Resolve only the legacy ``<VAR>`` form; newer syntaxes are
             # preserved verbatim for backward compatibility.

{apm_cli-0.16.1 → apm_cli-0.18.0}/src/apm_cli/adapters/client/copilot.py

@@ -26,7 +26,9 @@ from .base import (
     _extract_legacy_angle_vars,
     _has_env_placeholder,
     _stringify_env_literal,
-    _translate_env_placeholder,
+)
+from .base import (
+    _translate_env_placeholder as _translate_env_placeholder,
 )
 
 
@@ -117,12 +119,12 @@ class CopilotClientAdapter(MCPClientAdapter):
         """
         current_config = self.get_current_config()
 
-        # Ensure mcpServers section exists
-        if "mcpServers" not in current_config:
-            current_config["mcpServers"] = {}
+        # Ensure servers section exists and is a dict (guard against malformed config).
+        if not isinstance(current_config.get(self.mcp_servers_key), dict):
+            current_config[self.mcp_servers_key] = {}
 
         # Apply updates
-        current_config["mcpServers"].update(config_updates)
+        current_config[self.mcp_servers_key].update(config_updates)
 
         # Write back to file
         config_path = Path(self.get_config_path())
@@ -259,7 +261,7 @@ class CopilotClientAdapter(MCPClientAdapter):
             current = self.get_current_config()
         except Exception:
             return set(), False
-        servers = current.get("mcpServers") or {}
+        servers = current.get(self.mcp_servers_key) or {}
         # Match the same key resolution rule used below.
         if server_name:
             key = server_name
@@ -678,9 +680,9 @@ class CopilotClientAdapter(MCPClientAdapter):
         # ({NAME: value-or-placeholder}); registry-sourced deps pass a list
         # of {name, description, required} dicts. Translate-mode handling
         # for the dict shape: each value is either already a placeholder
-        # (translate it to the canonical ${VAR} form) or a literal (record
-        # the key as a placeholder reference and emit ${NAME} so the
-        # value never lands on disk). See issue #1152.
+        # (translate it to the adapter's runtime form) or a literal
+        # (record the key as a placeholder reference and emit a runtime
+        # placeholder so the value never lands on disk). See issue #1152.
         if isinstance(env_vars, dict) and self._supports_runtime_env_substitution:
             translated = {}
             placeholder_keys = []
@@ -694,9 +696,7 @@ class CopilotClientAdapter(MCPClientAdapter):
                     continue
                 if _has_env_placeholder(raw_value):
                     self._last_legacy_angle_vars.update(_extract_legacy_angle_vars(raw_value))
-                    translated[name] = _translate_env_placeholder(raw_value)
-                    # Record every ${VAR} in the translated value (handles
-                    # both ${env:VAR} -> ${VAR} and bare ${VAR} cases).
+                    translated[name] = self._translate_env_placeholder_for_runtime(raw_value)
                     for match in _ENV_VAR_RE.finditer(translated[name]):
                         placeholder_keys.append(match.group(1))
                 elif name in default_github_env and raw_value == default_github_env[name]:
@@ -704,7 +704,7 @@ class CopilotClientAdapter(MCPClientAdapter):
                 else:
                     # Literal value present in apm.yml -- replace with a
                     # runtime placeholder so the secret never touches disk.
-                    translated[name] = "${" + name + "}"
+                    translated[name] = self._format_runtime_env_placeholder(name)
                     placeholder_keys.append(name)
             self._last_env_placeholder_keys = set(placeholder_keys)
             return translated
@@ -722,10 +722,9 @@ class CopilotClientAdapter(MCPClientAdapter):
                     # Non-secret literal default -- preserve as-is.
                     resolved[name] = default_github_env[name]
                 else:
-                    # Emit a runtime-substitution placeholder; Copilot CLI
-                    # resolves ``${NAME}`` from the host environment at
-                    # server-start. APM never reads or stores the value.
-                    resolved[name] = "${" + name + "}"
+                    # Emit a runtime-substitution placeholder; APM never reads
+                    # or stores the value.
+                    resolved[name] = self._format_runtime_env_placeholder(name)
                     placeholder_keys.append(name)
             # Record for the post-install summary line and the
             # security-improvement notice.
@@ -783,7 +782,7 @@ class CopilotClientAdapter(MCPClientAdapter):
             # them (the env-block path tracks via _resolve_environment_variables).
             for match in _ENV_VAR_RE.finditer(value):
                 self._last_env_placeholder_keys.add(match.group(1))
-            return _translate_env_placeholder(value)
+            return self._translate_env_placeholder_for_runtime(value)
 
         import sys
 

apm_cli-0.18.0/src/apm_cli/adapters/client/intellij.py

@@ -0,0 +1,104 @@
+"""JetBrains Copilot implementation of the MCP client adapter.
+
+GitHub Copilot for JetBrains IDEs stores MCP server configuration under
+a user-scope directory whose location is OS-dependent:
+
+  Windows  : %LOCALAPPDATA%\\github-copilot\\intellij\\mcp.json
+  macOS    : ~/Library/Application Support/github-copilot/intellij/mcp.json
+  Linux    : $XDG_DATA_HOME/github-copilot/intellij/mcp.json
+               (defaults to ~/.local/share/github-copilot/intellij/mcp.json)
+
+The configuration file uses a top-level ``"servers"`` key (unlike most
+other Copilot-family adapters which use ``"mcpServers"``).
+
+Ref: https://github.com/orgs/community/discussions/139762
+"""
+
+import os
+import sys
+from pathlib import Path
+
+from ...utils.path_security import PathTraversalError, ensure_path_within
+from .copilot import CopilotClientAdapter
+
+
+def _intellij_config_dir() -> Path:
+    """Return the OS-specific JetBrains Copilot config directory.
+
+    Does not guarantee the directory exists; callers that need to write
+    to it should call ``mkdir(parents=True, exist_ok=True)`` first.
+
+    Raises
+    ------
+    PathTraversalError
+        If the environment variable the location is derived from
+        (``LOCALAPPDATA`` on Windows, ``XDG_DATA_HOME`` on Linux) is unset
+        or not absolute.  Without this guard an empty ``LOCALAPPDATA``
+        would yield ``Path("")`` -- a *relative* path -- causing APM to
+        silently read/write ``./github-copilot/intellij/mcp.json`` in the
+        current working directory and to falsely auto-detect the runtime.
+    """
+    if sys.platform == "win32":
+        local_app_data = os.environ.get("LOCALAPPDATA", "")
+        if not local_app_data or not os.path.isabs(local_app_data):
+            raise PathTraversalError(
+                "LOCALAPPDATA is unset or not an absolute path; cannot locate the "
+                "JetBrains Copilot configuration directory."
+            )
+        return Path(local_app_data) / "github-copilot" / "intellij"
+
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Application Support" / "github-copilot" / "intellij"
+
+    # Linux: honour $XDG_DATA_HOME, fall back to ~/.local/share
+    xdg_data = os.environ.get("XDG_DATA_HOME", "")
+    if xdg_data:
+        if not os.path.isabs(xdg_data):
+            raise PathTraversalError(
+                "XDG_DATA_HOME is set to a non-absolute path; cannot locate the "
+                "JetBrains Copilot configuration directory."
+            )
+        return Path(xdg_data) / "github-copilot" / "intellij"
+    return Path.home() / ".local" / "share" / "github-copilot" / "intellij"
+
+
+class IntelliJClientAdapter(CopilotClientAdapter):
+    """MCP client adapter for GitHub Copilot inside JetBrains IDEs.
+
+    JetBrains Copilot stores server definitions in a user-scope JSON file
+    with a ``"servers"`` top-level key (not ``"mcpServers"``).  This adapter
+    inherits registry-resolution and config read/write from
+    :class:`CopilotClientAdapter` and overrides the config path,
+    ``mcp_servers_key``, and runtime env-var placeholder syntax so the parent
+    methods operate on the correct schema.
+    """
+
+    supports_user_scope: bool = True
+    _client_label: str = "JetBrains Copilot"
+    target_name: str = "intellij"
+    mcp_servers_key: str = "servers"
+
+    # JetBrains Copilot resolves ${env:VAR} placeholders in mcp.json at
+    # server-start, so APM must not bake matching host secrets to disk.
+    _supports_runtime_env_substitution: bool = True
+
+    def _format_runtime_env_placeholder(self, name: str) -> str:
+        """Return JetBrains Copilot's native env-var placeholder syntax."""
+        return "${env:" + name + "}"
+
+    # ------------------------------------------------------------------ #
+    # Config path
+    # ------------------------------------------------------------------ #
+
+    def get_config_path(self) -> str:
+        """Return the OS-specific path to ``mcp.json`` for JetBrains Copilot.
+
+        The config directory is derived from an environment variable
+        (``LOCALAPPDATA`` / ``XDG_DATA_HOME``).  Validate it resolves
+        inside the user's home directory before any read/write so a
+        tampered or unexpected environment cannot redirect APM's writes
+        outside the user-scope tree (supply-chain hardening).
+        """
+        config_dir = _intellij_config_dir()
+        ensure_path_within(config_dir, Path.home())
+        return str(config_dir / "mcp.json")

{apm_cli-0.16.1 → apm_cli-0.18.0}/src/apm_cli/adapters/client/vscode.py

@@ -6,7 +6,6 @@ https://code.visualstudio.com/docs/copilot/chat/mcp-servers
 """
 
 import json
-import os  # noqa: F401
 import re
 from pathlib import Path
 

{apm_cli-0.16.1 → apm_cli-0.18.0}/src/apm_cli/bundle/lockfile_enrichment.py

@@ -2,7 +2,6 @@
 
 import posixpath
 from datetime import datetime, timezone
-from typing import Dict, List, Tuple, Union  # noqa: F401, UP035
 
 from ..deps.lockfile import LockFile
 from ..integration.targets import KNOWN_TARGETS

{apm_cli-0.16.1 → apm_cli-0.18.0}/src/apm_cli/bundle/packer.py

@@ -1,11 +1,9 @@
 """Bundle packer  -- creates self-contained APM bundles from the resolved dependency tree."""
 
-import os  # noqa: F401
 import shutil
 import tarfile
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Dict, List, Optional, Union  # noqa: F401, UP035
 
 from ..core.target_detection import detect_target
 from ..deps.lockfile import LockFile, get_lockfile_path, migrate_lockfile_if_needed

{apm_cli-0.16.1 → apm_cli-0.18.0}/src/apm_cli/bundle/plugin_exporter.py

@@ -9,12 +9,10 @@ under ``pack.bundle_files`` (issue #1098).
 
 import hashlib
 import json
-import os  # noqa: F401
 import re
 import shutil
 import tarfile
 from pathlib import Path, PurePosixPath
-from typing import Dict, List, Optional, Set, Tuple  # noqa: F401, UP035
 
 import yaml
 
@@ -25,7 +23,7 @@ from ..deps.lockfile import (
     migrate_lockfile_if_needed,
 )
 from ..models.apm_package import APMPackage, DependencyReference
-from ..utils.console import _rich_info, _rich_warning
+from ..utils.console import _rich_warning
 from ..utils.path_security import PathTraversalError, ensure_path_within, safe_rmtree
 from .packer import PackResult
 
@@ -270,17 +268,9 @@ def _collect_hooks_from_root(package_root: Path) -> dict:
 
 def _collect_mcp(package_root: Path) -> dict:
     """Return ``mcpServers`` dict from ``.mcp.json``."""
-    mcp_file = package_root / ".mcp.json"
-    if not mcp_file.is_file() or mcp_file.is_symlink():
-        return {}
-    try:
-        data = json.loads(mcp_file.read_text(encoding="utf-8"))
-        if isinstance(data, dict):
-            servers = data.get("mcpServers", {})
-            return dict(servers) if isinstance(servers, dict) else {}
-    except (json.JSONDecodeError, OSError):
-        pass
-    return {}
+    from ..core.plugin_manifest import collect_mcp_servers
+
+    return collect_mcp_servers(package_root)
 
 
 # ---------------------------------------------------------------------------
@@ -339,42 +329,15 @@ def _find_or_synthesize_plugin_json(
     suppress_missing_warning: bool = False,
     logger=None,
 ) -> dict:
-    """Locate an existing ``plugin.json`` or synthesise one from ``apm.yml``.
-
-    ``suppress_missing_warning`` silences the "no plugin.json on disk"
-    message when the caller knows synthesis is the expected path -- for
-    example a marketplace-publishing run that happens to have
-    ``dependencies:`` for local dev. Genuine parse errors on an existing
-    file are always surfaced.
-    """
-    from ..deps.plugin_parser import synthesize_plugin_json_from_apm_yml
-    from ..utils.helpers import find_plugin_json
-
-    plugin_json_path = find_plugin_json(project_root)
-    if plugin_json_path is not None:
-        try:
-            return json.loads(plugin_json_path.read_text(encoding="utf-8"))
-        except (json.JSONDecodeError, OSError) as exc:
-            _warn_msg = (
-                f"Found plugin.json at {plugin_json_path} but could not parse it: {exc}. "
-                "Falling back to synthesis from apm.yml."
-            )
-            if logger:
-                logger.warning(_warn_msg)
-            else:
-                _rich_warning(_warn_msg)
+    """Locate an existing ``plugin.json`` or synthesise one from ``apm.yml``."""
+    from ..core.plugin_manifest import find_or_synthesize_plugin_json
 
-    elif not suppress_missing_warning:
-        # Demoted from warning to info: synthesis from apm.yml is the
-        # APM-native happy path for plugin authoring, not a defect.
-        _info_msg = (
-            "No plugin.json on disk; deriving it from apm.yml (the APM-native source of truth)."
-        )
-        if logger:
-            logger.info(_info_msg)
-        else:
-            _rich_info(_info_msg)
-    return synthesize_plugin_json_from_apm_yml(apm_yml_path)
+    return find_or_synthesize_plugin_json(
+        project_root,
+        apm_yml_path,
+        suppress_missing_warning=suppress_missing_warning,
+        logger=logger,
+    )
 
 
 def _has_marketplace_block(apm_yml_path: Path) -> bool:

{apm_cli-0.16.1 → apm_cli-0.18.0}/src/apm_cli/bundle/unpacker.py

@@ -6,7 +6,6 @@ import tarfile
 import tempfile
 from dataclasses import dataclass, field
 from pathlib import Path, PureWindowsPath
-from typing import Dict, List  # noqa: F401, UP035
 
 from ..deps.lockfile import LEGACY_LOCKFILE_NAME, LOCKFILE_NAME, LockFile
 from ..utils.path_security import PathTraversalError, validate_path_segments

{apm_cli-0.16.1 → apm_cli-0.18.0}/src/apm_cli/cli.py

@@ -24,9 +24,11 @@ from apm_cli.commands.config import config
 from apm_cli.commands.deps import deps
 from apm_cli.commands.doctor import doctor
 from apm_cli.commands.experimental import experimental
+from apm_cli.commands.find import find as find_cmd
 from apm_cli.commands.init import init
 from apm_cli.commands.install import install
 from apm_cli.commands.list_cmd import list as list_cmd
+from apm_cli.commands.lock import lock
 from apm_cli.commands.marketplace import marketplace
 from apm_cli.commands.marketplace import search as marketplace_search
 from apm_cli.commands.mcp import mcp
@@ -50,6 +52,7 @@ _CLI_EPILOG = (
     "  apm init                       Scaffold a new project\n"
     "  apm install                    Install dependencies from apm.yml\n"
     "  apm install --frozen           Reproduce lockfile exactly (CI-safe)\n"
+    "  apm lock                       Resolve deps and write lockfile only\n"
     "  apm outdated                   See what's drifted from upstream\n"
     "  apm update                     Refresh refs and rewrite the lockfile\n"
     "  apm audit --ci                 Validate lockfile integrity for CI gates\n"
@@ -108,6 +111,7 @@ cli.add_command(unpack_cmd, name="unpack")
 cli.add_command(publish_cmd, name="publish")
 cli.add_command(init)
 cli.add_command(install)
+cli.add_command(lock)
 cli.add_command(uninstall)
 cli.add_command(prune)
 cli.add_command(update)
@@ -126,6 +130,7 @@ cli.add_command(policy)
 cli.add_command(outdated_cmd, name="outdated")
 cli.add_command(doctor)
 cli.add_command(marketplace)
+cli.add_command(find_cmd)
 cli.add_command(marketplace_search, name="search")
 
 

{apm_cli-0.16.1 → apm_cli-0.18.0}/src/apm_cli/commands/_apm_yml_writer.py

@@ -6,7 +6,6 @@ field.  Keeps write-back logic isolated and unit-testable.
 """
 
 from pathlib import Path
-from typing import List, Optional  # noqa: F401, UP035
 
 from ..models.dependency.reference import DependencyReference
 from ..utils.yaml_io import dump_yaml, load_yaml

{apm_cli-0.16.1 → apm_cli-0.18.0}/src/apm_cli/commands/_helpers.py

@@ -14,14 +14,15 @@ from colorama import Fore, Style
 from colorama import init as colorama_init
 
 from ..constants import (
-    APM_LOCK_FILENAME,  # noqa: F401
     APM_MODULES_DIR,
     APM_MODULES_GITIGNORE_PATTERN,
     APM_YML_FILENAME,
     GITIGNORE_FILENAME,
 )
 from ..update_policy import get_update_hint_message, is_self_update_enabled
-from ..utils.atomic_io import atomic_write_text as _atomic_write  # noqa: F401
+from ..utils.atomic_io import (
+    atomic_write_text as _atomic_write,  # noqa: F401 -- re-exported; tests import from apm_cli.commands._helpers
+)
 from ..utils.console import _rich_echo, _rich_info, _rich_warning
 from ..utils.path_security import PathTraversalError, validate_path_segments
 from ..utils.version_checker import check_for_updates
@@ -331,6 +332,74 @@ def _check_orphaned_packages():
         return []
 
 
+# ------------------------------------------------------------------
+# Dependency-update helpers (shared by `apm update` and `apm deps update`)
+# ------------------------------------------------------------------
+
+
+class UnknownPackageError(Exception):
+    """A requested package token matched no declared dependency.
+
+    Carries the offending *token* and the list of *available* display
+    names so the CLI caller can render a consistent error message.
+    """
+
+    def __init__(self, token: str, available: list[str]):
+        self.token = token
+        self.available = available
+        super().__init__(f"Package '{token}' not found")
+
+
+def resolve_requested_packages(
+    packages: tuple[str, ...] | list[str],
+    all_deps: list,
+) -> list[str] | None:
+    """Map requested package tokens to canonical dependency keys.
+
+    The install engine matches ``only_packages`` by ``DependencyReference``
+    identity (e.g. ``owner/repo``), so short names like ``compliance-rules``
+    must be normalised to their canonical key before the engine is called.
+
+    Args:
+        packages: Raw tokens from the CLI ``[PACKAGES]...`` argument.
+        all_deps: Declared dependencies (direct + dev) to match against.
+
+    Returns:
+        An order-preserving, de-duplicated list of canonical keys, or
+        ``None`` when *packages* is empty (meaning "refresh everything").
+
+    Raises:
+        UnknownPackageError: when a token matches no declared dependency.
+    """
+    if not packages:
+        return None
+
+    token_to_canonical: dict[str, str] = {}
+    for dep in all_deps:
+        canonical_key = dep.get_unique_key() or dep.repo_url or dep.get_display_name()
+        tokens = {canonical_key, dep.get_display_name(), dep.repo_url}
+        if getattr(dep, "alias", None):
+            tokens.add(dep.alias)
+        parts = dep.repo_url.split("/")
+        if len(parts) >= 2:
+            tokens.add(parts[-1])
+        for token in tokens:
+            if token and token not in token_to_canonical:
+                token_to_canonical[token] = canonical_key
+
+    resolved: list[str] = []
+    seen: set[str] = set()
+    for pkg in packages:
+        canonical = token_to_canonical.get(pkg)
+        if not canonical:
+            available = [dep.get_display_name() for dep in all_deps]
+            raise UnknownPackageError(pkg, available)
+        if canonical not in seen:
+            seen.add(canonical)
+            resolved.append(canonical)
+    return resolved
+
+
 def print_version(ctx, param, value):
     """Print version and exit."""
     if not value or ctx.resilient_parsing:
@@ -656,3 +725,23 @@ def _create_minimal_apm_yml(config, plugin=False, target_path=None):
         content = content.replace("dependencies:", skeleton + "\ndependencies:", 1)
 
     out_file.write_text(content, encoding="utf-8")
+
+
+def _find_apm_yml(start: Path | None = None) -> Path | None:
+    """Walk parent directories from ``start`` (or cwd) to find ``apm.yml``.
+
+    Matches the npm / cargo / poetry ergonomic: a developer running
+    an ``apm`` command from a subdirectory of their project (``src/``,
+    ``docs/``, ``scripts/``) finds the manifest and operates on it.
+
+    The walk stops at the filesystem root or when an ``apm.yml`` is
+    found, whichever comes first. Returns the absolute path to the
+    ``apm.yml`` file when found; ``None`` when no project root is
+    discoverable from ``start`` upward.
+    """
+    cwd = (start or Path.cwd()).resolve()
+    for candidate in (cwd, *cwd.parents):
+        manifest = candidate / "apm.yml"
+        if manifest.is_file():
+            return manifest
+    return None