apm-cli 0.31.0__tar.gz → 0.32.0__tar.gz

{apm_cli-0.31.0/src/apm_cli.egg-info → apm_cli-0.32.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: apm-cli
-Version: 0.31.0
+Version: 0.32.0
 Summary: MCP configuration tool
 Author-email: Daniel Meppiel <user@example.com>
 License: MIT License
@@ -67,7 +67,7 @@ Requires-Dist: pylint>=3.0.0; extra == "dev"
 Requires-Dist: hypothesis>=6.0.0; extra == "dev"
 Requires-Dist: mutmut==3.6.0; extra == "dev"
 Provides-Extra: build
-Requires-Dist: pyinstaller>=6.0.0; extra == "build"
+Requires-Dist: pyinstaller>=6.17.0; extra == "build"
 Dynamic: license-file
 
 # APM – Agent Package Manager

{apm_cli-0.31.0 → apm_cli-0.32.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "apm-cli"
-version = "0.31.0"
+version = "0.32.0"
 description = "MCP configuration tool"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -56,7 +56,7 @@ dev = [
     "mutmut==3.6.0",
 ]
 build = [
-    "pyinstaller>=6.0.0",
+    "pyinstaller>=6.17.0",
 ]
 
 [project.scripts]

{apm_cli-0.31.0 → apm_cli-0.32.0}/src/apm_cli/cache/git_cache.py

@@ -33,6 +33,7 @@ import re
 import subprocess
 from pathlib import Path
 
+from ..utils.atomic_io import atomic_write_text
 from ..utils.git_sparse import apply_sparse_cone, repair_dangling_cone_symlinks
 from ..utils.path_security import ensure_path_within
 from .integrity import verify_checkout_sha
@@ -278,6 +279,31 @@ class GitCache:
             promisor_url=url if use_partial else None,
         )
 
+    def _resolved_ref_path(self, url: str, ref: str) -> Path:
+        digest = hashlib.sha256(ref.encode("utf-8")).hexdigest()
+        path = self._db_root / f"{cache_shard_key(url)}-{digest}.ref"
+        ensure_path_within(path, self._db_root)
+        return path
+
+    def remember_resolved_ref(self, url: str, ref: str, sha: str) -> None:
+        """Persist an authorized remote observation independently of bare flavor."""
+        if not ref or not _SHA_RE.fullmatch(sha):
+            raise ValueError("A remote ref observation requires a ref and full SHA")
+        path = self._resolved_ref_path(url, ref)
+        with shard_lock(path):
+            atomic_write_text(path, sha.lower(), new_file_mode=0o600)
+
+    def read_resolved_ref(self, url: str, ref: str) -> tuple[bool, str | None]:
+        """Return receipt presence and SHA; corrupt receipts must not revive old refs."""
+        path = self._resolved_ref_path(url, ref)
+        try:
+            sha = path.read_text(encoding="ascii")
+        except FileNotFoundError:
+            return False, None
+        except (OSError, UnicodeError):
+            return True, None
+        return True, sha if _SHA_RE.fullmatch(sha) else None
+
     def _record_checkout_access(self, checkout_dir: Path) -> Path:
         """Record successful reuse of a finalized checkout under its shard lock."""
         # Pruning ages the shared SHA root, not individual checkout variants.
@@ -960,6 +986,8 @@ class GitCache:
                 if entry.is_dir(follow_symlinks=False) and not entry.name.endswith(".lock"):
                     db_count += 1
                     total_size += _dir_size(Path(entry.path))
+                elif entry.name.endswith(".ref") and entry.is_file(follow_symlinks=False):
+                    total_size += entry.stat(follow_symlinks=False).st_size
 
         if self._checkouts_root.is_dir():
             for shard_entry in os.scandir(str(self._checkouts_root)):

{apm_cli-0.31.0 → apm_cli-0.32.0}/src/apm_cli/cli.py

@@ -6,6 +6,7 @@ Thin wiring layer  -- all command logic lives in ``apm_cli.commands.*`` modules.
 # ruff: noqa: E402
 
 import ctypes
+import importlib
 import logging
 import os
 import sys
@@ -25,7 +26,6 @@ from apm_cli.commands._helpers import (
     print_version,
 )
 from apm_cli.commands.approve import approve_cmd, deny_cmd
-from apm_cli.commands.audit import audit
 from apm_cli.commands.cache import cache
 from apm_cli.commands.compile import compile as compile_cmd
 from apm_cli.commands.config import config
@@ -35,25 +35,18 @@ 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.lifecycle import lifecycle
 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
 from apm_cli.commands.outdated import outdated as outdated_cmd
-from apm_cli.commands.pack import pack_cmd, unpack_cmd
 from apm_cli.commands.plugin import plugin as plugin_cmd
 from apm_cli.commands.policy import policy
-from apm_cli.commands.prune import prune
 from apm_cli.commands.publish import publish_cmd
 from apm_cli.commands.run import preview, run
 from apm_cli.commands.runtime import runtime
 from apm_cli.commands.self_update import self_update
 from apm_cli.commands.targets import targets
-from apm_cli.commands.uninstall import uninstall
-from apm_cli.commands.update import update
 from apm_cli.commands.view import view as view_cmd
 
 _CLI_EPILOG = (
@@ -71,6 +64,85 @@ _CLI_EPILOG = (
 )
 
 
+class _LazyCommand(click.Command):
+    """Stub whose real Click object is imported on first dispatch.
+
+    Root ``apm --help`` only needs name/help/hidden, so heavyweight modules
+    stay unloaded until the matching verb is invoked or its own ``--help``.
+    """
+
+    def __init__(self, name: str, module: str, attr: str, help: str) -> None:
+        super().__init__(name=name, help=help)
+        self._module = module
+        self._attr = attr
+
+    def resolve(self) -> click.Command:
+        """Import and return the real command object."""
+        loaded = getattr(importlib.import_module(self._module), self._attr)
+        if not isinstance(loaded, click.Command):
+            raise TypeError(f"{self._module}.{self._attr} is not a Click command")
+        return loaded
+
+
+# Heavyweight verbs: imported only when the named subcommand is dispatched.
+_LAZY_COMMANDS: tuple[tuple[str, str, str, str], ...] = (
+    (
+        "audit",
+        "apm_cli.commands.audit",
+        "audit",
+        "Scan installed primitives for hidden Unicode, drift, and lockfile/policy violations",
+    ),
+    (
+        "install",
+        "apm_cli.commands.install",
+        "install",
+        "Install APM, MCP, and LSP dependencies (supports APM packages, Claude skills (SKILL.md), and plugin collections (plugin.json); auto-creates apm.yml; use --allow-insecure for http:// packages)",
+    ),
+    (
+        "marketplace",
+        "apm_cli.commands.marketplace",
+        "marketplace",
+        "Manage marketplaces for discovery and governance",
+    ),
+    (
+        "pack",
+        "apm_cli.commands.pack",
+        "pack_cmd",
+        "Pack distributable artifacts from your APM project.",
+    ),
+    (
+        "prune",
+        "apm_cli.commands.prune",
+        "prune",
+        "Remove APM packages absent from the resolved dependency graph and repair stale deployment owners",
+    ),
+    (
+        "search",
+        "apm_cli.commands.marketplace",
+        "search",
+        "Search plugins in a marketplace (QUERY@MARKETPLACE)",
+    ),
+    (
+        "uninstall",
+        "apm_cli.commands.uninstall",
+        "uninstall",
+        "Remove packages using manifest entries or direct locked keys from 'apm deps list'",
+    ),
+    (
+        "unpack",
+        "apm_cli.commands.pack",
+        "unpack_cmd",
+        "[Deprecated] Extract an APM bundle into the current project. Use 'apm install <bundle-path>' instead -- this command will be removed in a future release.",
+    ),
+    (
+        "update",
+        "apm_cli.commands.update",
+        "update",
+        "Refresh APM dependencies to the latest matching refs",
+    ),
+)
+
+
 class _OutputModeGroup(click.Group):
     """Capture full argv so root output mode precedes subcommand callbacks."""
 
@@ -78,6 +150,44 @@ class _OutputModeGroup(click.Group):
         ctx.meta["apm_raw_args"] = tuple(args)
         return super().parse_args(ctx, args)
 
+    def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None:
+        cmd = super().get_command(ctx, cmd_name)
+        if isinstance(cmd, _LazyCommand):
+            resolved = cmd.resolve()
+            self.commands[cmd_name] = resolved
+            return resolved
+        return cmd
+
+    def format_commands(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        """List subcommands from stubs so root --help does not import them."""
+        commands: list[tuple[str, click.Command]] = []
+        for subcommand in self.list_commands(ctx):
+            cmd = self.commands.get(subcommand)
+            if cmd is None or cmd.hidden:
+                continue
+            commands.append((subcommand, cmd))
+
+        if commands:
+            limit = formatter.width - 6 - max(len(name) for name, _cmd in commands)
+            rows = [(subcommand, cmd.get_short_help_str(limit)) for subcommand, cmd in commands]
+            if rows:
+                with formatter.section("Commands"):
+                    formatter.write_dl(rows)
+
+    def shell_complete(self, ctx: click.Context, incomplete: str) -> list:
+        """Complete from stubs so tab-complete does not import lazy verbs."""
+        from click.shell_completion import CompletionItem
+
+        results = [
+            CompletionItem(name, help=command.get_short_help_str())
+            for name in self.list_commands(ctx)
+            if name.startswith(incomplete)
+            for command in (self.commands.get(name),)
+            if command is not None and not command.hidden
+        ]
+        results.extend(click.Command.shell_complete(self, ctx, incomplete))
+        return results
+
 
 def _configure_logging(verbose: bool = False) -> None:
     """Configure stdlib logging for the ``apm_cli`` package.
@@ -187,7 +297,6 @@ def cli(ctx, verbose: bool) -> None:
 
 # Register command groups
 cli.add_command(approve_cmd, name="approve")
-cli.add_command(audit)
 cli.add_command(cache)
 cli.add_command(deny_cmd, name="deny")
 cli.add_command(deps)
@@ -202,16 +311,10 @@ cli.add_command(
         hidden=True,
     )
 )
-cli.add_command(pack_cmd, name="pack")
-cli.add_command(unpack_cmd, name="unpack")
 cli.add_command(publish_cmd, name="publish")
 cli.add_command(init)
 cli.add_command(discover)
-cli.add_command(install)
 cli.add_command(lock)
-cli.add_command(uninstall)
-cli.add_command(prune)
-cli.add_command(update)
 cli.add_command(self_update)
 cli.add_command(plugin_cmd, name="plugin")
 cli.add_command(compile_cmd, name="compile")
@@ -227,9 +330,12 @@ cli.add_command(policy)
 cli.add_command(outdated_cmd, name="outdated")
 cli.add_command(doctor)
 cli.add_command(lifecycle)
-cli.add_command(marketplace)
 cli.add_command(find_cmd)
-cli.add_command(marketplace_search, name="search")
+for _lazy_name, _lazy_module, _lazy_attr, _lazy_help in _LAZY_COMMANDS:
+    cli.add_command(
+        _LazyCommand(name=_lazy_name, module=_lazy_module, attr=_lazy_attr, help=_lazy_help),
+        name=_lazy_name,
+    )
 
 
 def _get_current_code_page() -> "Optional[int]":

{apm_cli-0.31.0 → apm_cli-0.32.0}/src/apm_cli/commands/_helpers.py

@@ -19,6 +19,7 @@ from ..constants import (
     APM_MODULES_GITIGNORE_PATTERN,
     APM_YML_FILENAME,
     GITIGNORE_FILENAME,
+    SKILL_MD_FILENAME,
 )
 from ..core import project_name as _project_name
 from ..update_policy import get_update_hint_message, is_self_update_enabled
@@ -191,7 +192,7 @@ def _expand_with_ancestors(
     unless that path is also directly declared in *paths*. Callers should
     pass only the subset of installed paths that look like *real
     standalone packages* (i.e., directories that ship their own
-    ``apm.yml``) -- not filesystem intermediaries (which typically have
+    ``apm.yml`` or ``SKILL.md``) -- not filesystem intermediaries (which typically have
     only a ``.apm/`` subtree from a cloned subdir dep). This preserves
     orphan detection for the case where a user has a genuinely orphaned
     ``owner/repo`` package on disk alongside a declared sibling
@@ -256,19 +257,17 @@ def _standalone_installed_packages(
     1. Path appears as a dependency key in *lockfile* -- the canonical
        record of what APM installed. The lockfile is integrity-checked
        and not forgeable by dropping/omitting files in ``apm_modules/``.
-    2. Fallback: path has its own ``apm.yml``. Used when the lockfile
+    2. Fallback: path has its own ``apm.yml`` or ``SKILL.md`` file. Used when the lockfile
        is absent (older installs / fresh checkouts) or does not list
        the key. A directory with only a ``.apm/`` marker is treated as
        a filesystem intermediary, not a standalone package.
 
-    Combining both signals closes the suppression-via-absence gap
-    (panel finding: forgeable ``apm.yml`` heuristic) while preserving
-    behaviour for projects that pre-date the lockfile or have not yet
-    re-installed.
+    Package markers preserve standalone orphan detection even when a
+    declaration points at a subdirectory of a removed package root.
 
     Failure mode: only narrowly-typed shape errors against
     ``lockfile.dependencies`` (``AttributeError`` / ``TypeError`` /
-    ``KeyError``) are absorbed and degrade to the ``apm.yml``-only
+    ``KeyError``) are absorbed and degrade to the package-marker
     fallback. Any other exception (e.g. lockfile parse / I/O failure)
     propagates so the outer caller can decide whether to log or fail
     closed -- preventing a corrupted or attacker-crafted lockfile from
@@ -287,7 +286,9 @@ def _standalone_installed_packages(
         if p in lockfile_keys:
             standalone.append(p)
             continue
-        if (apm_modules_dir / p / APM_YML_FILENAME).exists():
+        if (apm_modules_dir / p / APM_YML_FILENAME).exists() or (
+            apm_modules_dir / p / SKILL_MD_FILENAME
+        ).is_file():
             standalone.append(p)
     return standalone
 
@@ -322,23 +323,44 @@ def _check_orphaned_packages():
             return []
 
         installed = _scan_installed_packages(apm_modules_dir)
-        # Combined lockfile-membership + apm.yml fallback determines
-        # which installed paths are real standalone packages (and so
-        # must NOT be masked by ancestor expansion). The lockfile is
-        # the canonical, tamper-evident record; apm.yml-existence is
-        # the fallback for projects without a lockfile yet.
-        # See _expand_with_ancestors for the user-safety rationale.
-        standalone_installed = _standalone_installed_packages(
-            installed, apm_modules_dir, lockfile=lockfile
-        )
-        expected_with_ancestors = _expand_with_ancestors(expected, standalone_installed)
-        # Sort for deterministic, diffable output across runs (rglob
-        # traversal order is filesystem-dependent).
-        return sorted(p for p in installed if p not in expected_with_ancestors)
+        return _find_orphaned_packages(installed, expected)
     except Exception:
         return []
 
 
+def _find_orphaned_packages(installed: Iterable[str], expected: set[str]) -> list[str]:
+    """Select roots unrelated to the retained dependency graph.
+
+    Keep both bundled descendants and whole roots containing needed children.
+    Ancestor prefixes protect only those containing roots, not their siblings.
+    Unlike dependency-list classification, deletion must retain recognized
+    ancestors at every depth, including aliases and hidden subdirectories.
+    """
+    roots = set()
+    retained = set(expected)
+    for path in expected:
+        try:
+            validate_path_segments(path, context="orphan selection")
+        except PathTraversalError:
+            # Invalid tokens protect only an exact match, never a wider subtree.
+            continue
+        normalized = path.replace("\\", "/")
+        roots.add(normalized)
+        parts = normalized.split("/")
+        retained.update("/".join(parts[:depth]) for depth in range(1, len(parts) + 1))
+
+    orphaned = []
+    for path in installed:
+        normalized = path.replace("\\", "/")
+        if normalized in retained:
+            continue
+        parts = normalized.split("/")
+        if any("/".join(parts[:depth]) in roots for depth in range(1, len(parts))):
+            continue
+        orphaned.append(path)
+    return sorted(orphaned)
+
+
 # ------------------------------------------------------------------
 # Dependency-update helpers (shared by `apm update` and `apm deps update`)
 # ------------------------------------------------------------------

{apm_cli-0.31.0 → apm_cli-0.32.0}/src/apm_cli/commands/deps/_utils.py

@@ -11,27 +11,32 @@ from ...utils.yaml_io import load_yaml
 def _scan_installed_packages(apm_modules_dir: Path) -> list:
     """Scan *apm_modules_dir* for installed package paths.
 
-    Walks the tree to find top-level directories containing ``apm.yml`` or
-    ``.apm``, supporting GitHub (2-level), ADO (3-level), and subdirectory
-    packages. Package manifests nested below another package are part of that
+    Walks the tree to find top-level directories containing ``apm.yml``,
+    ``.apm``, or ``SKILL.md``, supporting aliases (1-level), GitHub (2-level), ADO (3-level),
+    and subdirectory packages. Manifests nested below another package are part of that
     parent package and are excluded.
 
     Returns:
-        List of ``"owner/repo"`` or ``"org/project/repo"`` path keys.
+        List of installed relative paths, including flattened aliases.
     """
     installed: list = []
     if not apm_modules_dir.exists():
         return installed
     for candidate in apm_modules_dir.rglob("*"):
-        if not candidate.is_dir() or candidate.name.startswith("."):
+        if candidate.is_symlink() or not candidate.is_dir():
             continue
-        if not ((candidate / APM_YML_FILENAME).exists() or (candidate / APM_DIR).exists()):
+        if candidate.name.startswith(".") and candidate.parent != apm_modules_dir:
+            continue
+        if not (
+            (candidate / APM_YML_FILENAME).exists()
+            or (candidate / APM_DIR).exists()
+            or (candidate / SKILL_MD_FILENAME).is_file()
+        ):
             continue
         if _is_nested_under_package(candidate, apm_modules_dir):
             continue
         rel_parts = candidate.relative_to(apm_modules_dir).parts
-        if len(rel_parts) >= 2:
-            installed.append("/".join(rel_parts))
+        installed.append("/".join(rel_parts))
     return installed
 
 
@@ -41,7 +46,7 @@ def _is_nested_under_package(candidate: Path, apm_modules_path: Path) -> bool:
     When a package ships nested package or skill manifests, the ``rglob`` scan
     would otherwise treat each sub-directory as an independent package. This
     helper walks up from *candidate* towards *apm_modules_path* and returns
-    ``True`` if any intermediate parent already contains ``apm.yml``, ``.apm``,
+    ``True`` if any intermediate parent already contains ``apm.yml``, ``.apm``, ``SKILL.md``,
     or a canonical Agent Plugin manifest -- meaning the candidate is part of
     that package, not a standalone one.
     """
@@ -50,6 +55,7 @@ def _is_nested_under_package(candidate: Path, apm_modules_path: Path) -> bool:
         if (
             (parent / APM_YML_FILENAME).exists()
             or (parent / APM_DIR).exists()
+            or (parent / SKILL_MD_FILENAME).is_file()
             or _is_agent_plugin_root(parent)
         ):
             return True

{apm_cli-0.31.0 → apm_cli-0.32.0}/src/apm_cli/commands/doctor.py

@@ -12,8 +12,6 @@ import sys
 
 import click
 
-from .marketplace.doctor import run_doctor
-
 
 @click.command(
     help=(
@@ -25,6 +23,8 @@ from .marketplace.doctor import run_doctor
 @click.option("--verbose", "-v", is_flag=True, help="Show detailed output")
 def doctor(verbose):
     """Top-level diagnostic entry point."""
+    from .marketplace.doctor import run_doctor
+
     exit_code = run_doctor(verbose, logger_name="doctor")
     if exit_code != 0:
         sys.exit(exit_code)

{apm_cli-0.31.0 → apm_cli-0.32.0}/src/apm_cli/commands/marketplace/check.py

@@ -15,7 +15,7 @@ from ...marketplace.ref_resolver import RefResolver
 from ...marketplace.semver import satisfies_range
 from ...marketplace.yml_schema import PackageEntry
 from ...models.dependency.host_virtual import repository_owner
-from ...utils.github_host import is_azure_devops_hostname
+from ...utils.github_host import default_host, is_azure_devops_hostname
 from . import (
     _CheckResult,
     _extract_tag_versions,
@@ -90,17 +90,18 @@ def check(offline, verbose):
     # named a non-default host -- a host-prefixed source or a relative source
     # composed onto ``marketplace.sourceBase`` -- must be resolved against
     # that host with the host's (and, for sourceBase, the org's) token,
-    # exactly like ``apm pack`` does. Default-host entries keep the bare
-    # ambient-credential path.
+    # exactly like ``apm pack`` does. Default-host entries resolve the
+    # configured default host through the same authentication path.
     source_base = getattr(yml, "source_base", None)
     resolvers: dict[tuple[str | None, str | None], RefResolver] = {}
     auth_resolver: AuthResolver | None = None
 
     def _resolver_for(host: str | None, org: str | None) -> RefResolver:
         nonlocal auth_resolver
-        key = (host, org)
+        resolved_host = host or default_host() or "github.com"
+        key = (resolved_host, org)
         if key not in resolvers:
-            if host is None:
+            if host is None and offline:
                 resolvers[key] = RefResolver(offline=offline)
             else:
                 if auth_resolver is None and not offline:
@@ -108,14 +109,14 @@ def check(offline, verbose):
 
                     auth_resolver = AuthResolver()
                 auth = resolve_auth_for_host(
-                    host,
+                    resolved_host,
                     offline=offline,
                     org=org,
                     auth_resolver=auth_resolver,
                 )
                 resolvers[key] = RefResolver(
                     offline=offline,
-                    host=host,
+                    host=resolved_host,
                     token=auth.token if auth else None,
                     auth_scheme=auth.auth_scheme if auth else "basic",
                     git_env=(
@@ -124,7 +125,7 @@ def check(offline, verbose):
                         else None
                     ),
                     auth_resolver=auth_resolver,
-                    auth_target=host,
+                    auth_target=resolved_host,
                 )
         return resolvers[key]
 
@@ -156,7 +157,8 @@ def check(offline, verbose):
                 else:
                     remote_label = f"https://{host}/{owner_repo}.git" if host else owner_repo
                 logger.verbose_detail(
-                    f"Resolving {entry.name} via {host or 'default host'}: {remote_label}"
+                    f"Resolving {entry.name} via "
+                    f"{host or default_host() or 'github.com'}: {remote_label}"
                 )
                 refs = _resolver_for(host, org).list_remote_refs(owner_repo)
 

{apm_cli-0.31.0 → apm_cli-0.32.0}/src/apm_cli/commands/prune.py

@@ -21,9 +21,8 @@ from ..models.apm_package import APMPackage
 from ..utils.path_security import safe_rmtree
 from ._helpers import (
     _build_expected_install_paths,
-    _expand_with_ancestors,
+    _find_orphaned_packages,
     _scan_installed_packages,
-    _standalone_installed_packages,
 )
 from .uninstall.lockfile_state import lockfile_has_persisted_state
 
@@ -125,15 +124,6 @@ def prune(ctx, dry_run):
         installed_packages = (
             _scan_installed_packages(apm_modules_dir) if apm_modules_dir.exists() else set()
         )
-        standalone_installed = _standalone_installed_packages(
-            installed_packages,
-            apm_modules_dir,
-            lockfile=lockfile,
-        )
-        expected_with_ancestors = _expand_with_ancestors(
-            expected_installed,
-            standalone_installed,
-        )
         expected_lock_keys = {dependency.get_unique_key() for dependency in declared_deps}
         if lockfile is not None:
             expected_lock_keys.update(
@@ -144,14 +134,19 @@ def prune(ctx, dry_run):
         lock_keys_by_path = (
             _lock_keys_by_install_path(lockfile, apm_modules_dir) if lockfile is not None else {}
         )
-        orphaned_packages = sorted(
-            p for p in installed_packages if p not in expected_with_ancestors
+        orphaned_paths = set(
+            _find_orphaned_packages(
+                set(installed_packages) | set(lock_keys_by_path), expected_installed
+            )
         )
+        orphaned_packages = sorted(set(installed_packages) & orphaned_paths)
+        retained_packages = set(installed_packages) - orphaned_paths
+        for package in sorted(retained_packages - expected_installed):
+            logger.progress(f"Retained {package}: required package content.")
         missing_orphaned_keys = sorted(
             dep_key
             for relative_path, dep_keys in lock_keys_by_path.items()
-            if relative_path in expected_with_ancestors
-            or not (apm_modules_dir / relative_path).exists()
+            if relative_path not in orphaned_paths or not (apm_modules_dir / relative_path).exists()
             for dep_key in dep_keys
             if dep_key not in expected_lock_keys
         )
@@ -208,7 +203,7 @@ def prune(ctx, dry_run):
         if missing_orphaned_keys:
             logger.progress(
                 f"Found {len(missing_orphaned_keys)} stale lockfile dependency "
-                "record(s) without installed package content."
+                "record(s) without removable package content."
             )
 
         if dry_run:

{apm_cli-0.31.0 → apm_cli-0.32.0}/src/apm_cli/core/deployment_ledger.py

@@ -203,6 +203,31 @@ class DeploymentLedgerCodec:
             ),
         )
 
+    @staticmethod
+    def merge_dependencies(
+        lockfile: LockFile,
+        updated: LockFile,
+        *,
+        project_root: Path,
+        diagnostics: DiagnosticCollector,
+    ) -> None:
+        """Merge processed dependencies without discarding concrete deployment locators."""
+        current = DeploymentLedgerCodec.from_lockfile(updated)
+        retained = DeploymentLedgerCodec.reconcile_owner_references(
+            lockfile,
+            excluded_dependency_keys=updated.dependencies,
+            project_root=project_root,
+            diagnostics=diagnostics,
+        )
+        # add_dependency invalidates the legacy projection. Capture both
+        # canonical ledgers first, then restore their reconciled records once.
+        for dependency in updated.dependencies.values():
+            lockfile.add_dependency(dependency)
+        DeploymentLedgerCodec.apply_to_lockfile(
+            DeploymentLedger(records={**retained.ledger.records, **current.records}),
+            lockfile,
+        )
+
     @staticmethod
     def from_lockfile(lockfile: LockFile) -> DeploymentLedger:
         """Read canonical rows or synthesize them from legacy ownership views."""