apm-cli 0.29.1__tar.gz → 0.30.0__tar.gz

{apm_cli-0.29.1/src/apm_cli.egg-info → apm_cli-0.30.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: apm-cli
-Version: 0.29.1
+Version: 0.30.0
 Summary: MCP configuration tool
 Author-email: Daniel Meppiel <user@example.com>
 License: MIT License
@@ -170,7 +170,16 @@ apm-policy.yml governs what gets installed; your agent harness governs what runs
 
 ## Get Started
 
-#### Linux / macOS
+#### macOS with Homebrew
+
+```bash
+brew install apm
+```
+
+No custom tap is required. Homebrew manages installation and updates:
+use `brew upgrade apm`, not `apm self-update`.
+
+#### Linux / macOS without Homebrew
 
 ```bash
 curl -sSL https://aka.ms/apm-unix | sh
@@ -182,17 +191,17 @@ curl -sSL https://aka.ms/apm-unix | sh
 irm https://aka.ms/apm-windows | iex
 ```
 
-Native release binaries are published for macOS, Linux, and Windows x86_64. `apm self-update` reuses the matching platform installer.
+Native release binaries are published for macOS, Linux, and Windows x86_64.
+For standalone installations, `apm self-update` reuses the matching platform installer.
+You do not need Homebrew to use APM.
 
 <details>
-<summary>Other install methods</summary>
+<summary>Other install methods: pip and Scoop</summary>
 
 #### Linux / macOS
 
 ```bash
-# Homebrew
-brew install microsoft/apm/apm
-# pip
+# pip (Python 3.10+)
 pip install apm-cli
 ```
 
@@ -208,6 +217,9 @@ pip install apm-cli
 
 </details>
 
+Already using the Microsoft Homebrew tap? See the
+[migration guide](https://microsoft.github.io/apm/getting-started/installation/#migrate-from-the-microsoft-tap).
+
 Then start adding packages:
 
 ```bash

{apm_cli-0.29.1 → apm_cli-0.30.0}/README.md

@@ -98,7 +98,16 @@ apm-policy.yml governs what gets installed; your agent harness governs what runs
 
 ## Get Started
 
-#### Linux / macOS
+#### macOS with Homebrew
+
+```bash
+brew install apm
+```
+
+No custom tap is required. Homebrew manages installation and updates:
+use `brew upgrade apm`, not `apm self-update`.
+
+#### Linux / macOS without Homebrew
 
 ```bash
 curl -sSL https://aka.ms/apm-unix | sh
@@ -110,17 +119,17 @@ curl -sSL https://aka.ms/apm-unix | sh
 irm https://aka.ms/apm-windows | iex
 ```
 
-Native release binaries are published for macOS, Linux, and Windows x86_64. `apm self-update` reuses the matching platform installer.
+Native release binaries are published for macOS, Linux, and Windows x86_64.
+For standalone installations, `apm self-update` reuses the matching platform installer.
+You do not need Homebrew to use APM.
 
 <details>
-<summary>Other install methods</summary>
+<summary>Other install methods: pip and Scoop</summary>
 
 #### Linux / macOS
 
 ```bash
-# Homebrew
-brew install microsoft/apm/apm
-# pip
+# pip (Python 3.10+)
 pip install apm-cli
 ```
 
@@ -136,6 +145,9 @@ pip install apm-cli
 
 </details>
 
+Already using the Microsoft Homebrew tap? See the
+[migration guide](https://microsoft.github.io/apm/getting-started/installation/#migrate-from-the-microsoft-tap).
+
 Then start adding packages:
 
 ```bash

{apm_cli-0.29.1 → apm_cli-0.30.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "apm-cli"
-version = "0.29.1"
+version = "0.30.0"
 description = "MCP configuration tool"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -219,4 +219,5 @@ markers = [
     "req: binds a test to one or more OpenAPM req-XXX ids (spec-conformance suite)",
     "lifecycle_smoke: promoted to the required PR-time Lifecycle Smoke (Linux) job -- see ci.yml's lifecycle-smoke job and docs/src/content/docs/contributing/integration-testing.md",
     "lifecycle_merge_group: unique lifecycle contracts retained in the full merge-group integration suite",
+    "xdist_group(name): assigns HOME-mutating tests to one pytest-xdist loadgroup for process-level serialization",
 ]

apm_cli-0.30.0/src/apm_cli/cache/cleanup.py

@@ -0,0 +1,51 @@
+"""Verified, best-effort removal outcomes for explicit cache cleaning."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterable
+from pathlib import Path
+
+from ..utils import file_ops
+
+
+def clean_cache_buckets(buckets: Iterable[Path]) -> list[str]:
+    """Remove bucket children without following links; return all failure details.
+
+    Successful removals are not rolled back. The residual check is essential:
+    the read-only recovery callback in robust_rmtree can swallow OS errors.
+    """
+    failures: list[str] = []
+    for bucket in buckets:
+        try:
+            if bucket.is_symlink():
+                failures.append(f"{bucket}: refusing to traverse a symlinked cache bucket")
+                continue
+            with os.scandir(bucket) as entries:
+                for entry in entries:
+                    path = Path(entry.path)
+                    try:
+                        if entry.is_dir(follow_symlinks=False):
+                            file_ops.robust_rmtree(path)
+                        else:
+                            path.unlink()
+                    except FileNotFoundError:
+                        pass
+                    except OSError as exc:
+                        failures.append(f"{path}: {exc}")
+                        continue
+                    try:
+                        # lstat distinguishes a removed entry from an unreadable
+                        # one and also detects dangling symlinks.
+                        path.lstat()
+                    except FileNotFoundError:
+                        continue
+                    except OSError as exc:
+                        failures.append(f"{path}: {exc}")
+                    else:
+                        failures.append(f"{path}: entry remains after deletion")
+        except FileNotFoundError:
+            continue
+        except OSError as exc:
+            failures.append(f"{bucket}: {exc}")
+    return failures

{apm_cli-0.29.1 → apm_cli-0.30.0}/src/apm_cli/cache/git_cache.py

@@ -16,6 +16,7 @@ Resolution flow:
 On every cache HIT:
 - Run integrity check (verify HEAD == expected SHA)
 - Mismatch -> evict shard, fall through to fresh fetch, log warning
+- Refresh the SHA directory's access timestamp after successful validation
 
 Concurrency:
 - Per-shard file locks (via filelock) for atomic operations
@@ -24,7 +25,6 @@ Concurrency:
 
 from __future__ import annotations
 
-import contextlib
 import hashlib
 import json
 import logging
@@ -50,6 +50,15 @@ _FALLBACK_REFSPECS = (
 )
 
 
+class CachePruneError(OSError):
+    """Incomplete prune with completed-removal count and per-entry failures."""
+
+    def __init__(self, pruned: int, failures: list[tuple[Path, OSError]]) -> None:
+        self.pruned = pruned
+        self.failures = tuple(failures)
+        super().__init__(f"Pruned {pruned} SHA group(s); {len(failures)} failed.")
+
+
 def _safe_git_args() -> list[str]:
     """Return hardening ``-c`` args prepended to every git subprocess.
 
@@ -195,11 +204,8 @@ class GitCache:
             if verify_checkout_sha(checkout_dir, sha):
                 _log.debug("Cache HIT: %s @ %s [%s]", _sanitize_url(url), sha[:12], variant)
                 with shard_lock(checkout_dir):
-                    return self._finalize_sparse_checkout(
-                        url,
-                        checkout_dir,
-                        sparse_paths,
-                        env=env,
+                    return self._record_checkout_access(
+                        self._finalize_sparse_checkout(url, checkout_dir, sparse_paths, env=env)
                     )
             else:
                 # Integrity failure -- evict
@@ -226,6 +232,21 @@ class GitCache:
             promisor_url=url if use_partial 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.
+        try:
+            os.utime(checkout_dir.parent, None)
+        except PermissionError as exc:
+            _log.warning(
+                "[!] Cannot update Git cache recency for %s: %s. "
+                "Continuing with validated checkout; cache prune may evict it. "
+                "Check cache permissions or set APM_CACHE_DIR to a writable directory.",
+                checkout_dir.parent,
+                exc,
+            )
+        return checkout_dir
+
     def _finalize_sparse_checkout(
         self,
         url: str,
@@ -600,11 +621,8 @@ class GitCache:
                     sha[:12],
                     variant,
                 )
-                return self._finalize_sparse_checkout(
-                    url,
-                    final_dir,
-                    sparse_paths,
-                    env=env,
+                return self._record_checkout_access(
+                    self._finalize_sparse_checkout(url, final_dir, sparse_paths, env=env)
                 )
 
             staged = stage_path(final_dir)
@@ -873,33 +891,37 @@ class GitCache:
             "total_size_bytes": total_size,
         }
 
-    def clean_all(self) -> None:
-        """Remove ALL cache content (db + checkouts). Used by ``apm cache clean``."""
-        from ..utils.file_ops import robust_rmtree
+    def clean_all(self) -> list[str]:
+        """Remove db and checkouts, returning details of every incomplete removal."""
+        from .cleanup import clean_cache_buckets
 
-        for bucket in (self._db_root, self._checkouts_root):
-            if bucket.is_dir():
-                for entry in os.scandir(str(bucket)):
-                    if entry.is_dir(follow_symlinks=False):
-                        robust_rmtree(Path(entry.path), ignore_errors=True)
-                    elif entry.is_file(follow_symlinks=False):
-                        with contextlib.suppress(OSError):
-                            os.unlink(entry.path)
+        return clean_cache_buckets((self._db_root, self._checkouts_root))
 
     def prune(self, *, max_age_days: int = 30) -> int:
         """Remove checkout entries older than *max_age_days*.
 
-        Uses mtime of the checkout directory as the access indicator.
+        Uses mtime of the shared SHA directory as the access indicator.
+        Successfully reusing any checkout variant refreshes that timestamp.
 
         Returns:
-            Number of entries pruned.
+            Number of SHA groups successfully removed.
+
+        Raises:
+            ValueError: If max_age_days is negative.
+            CachePruneError: Some entries could not be inspected or removed.
+                Other stale entries are still attempted. Completed removals
+                and partially deleted entries are not rolled back.
         """
         import time
 
         from ..utils.file_ops import robust_rmtree
 
+        if max_age_days < 0:
+            raise ValueError("max_age_days must be nonnegative; use 0 or a positive number of days")
+
         cutoff = time.time() - (max_age_days * 86400)
         pruned = 0
+        failures: list[tuple[Path, OSError]] = []
 
         if not self._checkouts_root.is_dir():
             return 0
@@ -913,11 +935,13 @@ class GitCache:
                 try:
                     stat = sha_entry.stat(follow_symlinks=False)
                     if stat.st_mtime < cutoff:
-                        robust_rmtree(Path(sha_entry.path), ignore_errors=True)
+                        robust_rmtree(Path(sha_entry.path))
                         pruned += 1
-                except OSError:
-                    continue
+                except OSError as exc:
+                    failures.append((Path(sha_entry.path), exc))
 
+        if failures:
+            raise CachePruneError(pruned, failures)
         return pruned
 
 

{apm_cli-0.29.1 → apm_cli-0.30.0}/src/apm_cli/cache/http_cache.py

@@ -121,6 +121,13 @@ class HttpCache:
                     robust_rmtree(entry_path, ignore_errors=True)
                     return None
 
+            # Recency is independent of TTL. A concurrent eviction or read-only
+            # cache must not discard the response we have already verified.
+            try:
+                os.utime(str(entry_path), None)
+            except OSError as exc:
+                _log.debug("Failed to update HTTP cache recency for %s: %s", url, exc)
+
             return CacheEntry(
                 body=body,
                 etag=meta.get("etag"),
@@ -270,14 +277,12 @@ class HttpCache:
         except (json.JSONDecodeError, OSError) as exc:
             _log.debug("Failed to refresh HTTP cache entry for %s: %s", url, exc)
 
-    def clean_all(self) -> None:
-        """Remove all HTTP cache entries."""
-        from ..utils.file_ops import robust_rmtree
+    def clean_all(self) -> list[str]:
+        """Remove HTTP entries, returning details of every incomplete removal."""
+        from .cleanup import clean_cache_buckets
 
-        if self._cache_dir.is_dir():
-            for entry in os.scandir(str(self._cache_dir)):
-                if entry.is_dir(follow_symlinks=False):
-                    robust_rmtree(Path(entry.path), ignore_errors=True)
+        self._tracked_size = None
+        return clean_cache_buckets((self._cache_dir,))
 
     def get_stats(self) -> dict[str, int]:
         """Return cache statistics.

{apm_cli-0.29.1 → apm_cli-0.30.0}/src/apm_cli/commands/cache.py

@@ -60,43 +60,51 @@ def info() -> None:
 def clean(force: bool, yes: bool) -> None:
     """Remove all cache content (git repos, checkouts, HTTP responses)."""
     from ..cache.paths import get_cache_root
-    from ..utils.console import _rich_info, _rich_success
+    from ..core.command_logger import CommandLogger
 
+    logger = CommandLogger("cache clean")
     try:
         root = get_cache_root()
     except (ValueError, OSError) as exc:
-        from ..utils.console import _rich_error
-
-        _rich_error(f"Cannot resolve cache root: {exc}", symbol="error")
+        logger.error(f"Cannot resolve cache root: {exc}")
         raise SystemExit(1) from exc
 
     if not force and not yes:
         confirmed = click.confirm(f"Remove all cache content in {root}?", default=False)
         if not confirmed:
-            _rich_info("Aborted.", symbol="info")
+            logger.progress("Aborted.")
             return
 
-    _rich_info("Cleaning cache...", symbol="gear")
+    logger.start("Cleaning cache...", symbol="gear")
 
     from ..cache.git_cache import GitCache
     from ..cache.http_cache import HttpCache
 
-    git_cache = GitCache(root)
-    git_cache.clean_all()
-
-    http_cache = HttpCache(root)
-    http_cache.clean_all()
-
-    _rich_success("Cache cleaned.", symbol="check")
-
-
-@cache.command(help="Remove cache entries older than N days")
+    failures: list[str] = []
+    for cache_type in (GitCache, HttpCache):
+        try:
+            failures.extend(cache_type(root).clean_all())
+        except OSError as exc:
+            failures.append(f"{cache_type.__name__}: {exc}")
+    if failures:
+        logger.error("Cache cleanup incomplete; some cached content could not be removed.")
+        for failure in failures:
+            logger.error(failure)
+        logger.error(
+            "Close processes using the cache, check permissions, then retry apm cache clean."
+        )
+        raise SystemExit(1)
+
+    logger.success("Cache cleaned.", symbol="check")
+
+
+@cache.command(help="Remove Git checkout SHA groups older than N days")
 @click.option(
     "--days",
-    type=int,
+    type=click.IntRange(min=0),
     default=30,
     show_default=True,
-    help="Remove entries not accessed within this many days",
+    help="Remove SHA groups not accessed within this many days",
 )
 def prune(days: int) -> None:
     """Remove stale cache entries based on last access time.
@@ -105,24 +113,31 @@ def prune(days: int) -> None:
     referenced by project lockfiles are NOT exempt -- freshness is
     determined solely by filesystem timestamps.
     """
-    from ..cache.git_cache import GitCache
+    from ..cache.git_cache import CachePruneError, GitCache
     from ..cache.paths import get_cache_root
-    from ..utils.console import _rich_info, _rich_success
+    from ..core.command_logger import CommandLogger
+
+    logger = CommandLogger("cache prune")
 
     try:
         root = get_cache_root()
     except (ValueError, OSError) as exc:
-        from ..utils.console import _rich_error
-
-        _rich_error(f"Cannot resolve cache root: {exc}", symbol="error")
+        logger.error(f"Cannot resolve cache root: {exc}")
         raise SystemExit(1) from exc
 
-    _rich_info(f"Pruning entries older than {days} days...", symbol="gear")
+    logger.start(f"Pruning SHA groups older than {days} days...", symbol="gear")
 
     git_cache = GitCache(root)
-    pruned = git_cache.prune(max_age_days=days)
+    try:
+        pruned = git_cache.prune(max_age_days=days)
+    except CachePruneError as exc:
+        logger.error(str(exc))
+        for path, error in exc.failures:
+            logger.error(f"Could not prune {path}: {error}")
+        logger.error("Check permissions or close programs using the cache, then retry.")
+        raise SystemExit(1) from exc
 
-    _rich_success(f"Pruned {pruned} checkout(s).", symbol="check")
+    logger.success(f"Pruned {pruned} SHA group(s).", symbol="check")
 
 
 def _format_size(size_bytes: int) -> str:

{apm_cli-0.29.1 → apm_cli-0.30.0}/src/apm_cli/commands/config.py

@@ -12,6 +12,7 @@ from ..constants import APM_YML_FILENAME
 from ..core.command_logger import CommandLogger
 from ..install.locking import serialized_lifecycle
 from ..version import get_version
+from . import self_update as self_update_command
 from ._helpers import HIGHLIGHT, RESET, _get_console, _load_apm_config
 
 # Restore builtin since a subcommand is named ``set``
@@ -473,7 +474,13 @@ def set(key, value):  # noqa: F811
 
         try:
             install_dir = set_self_update_install_dir(value)
-            logger.success(f"Self-update install directory saved: {install_dir}")
+            if self_update_command._is_windows_platform():
+                logger.success(f"Self-update install directory saved: {install_dir}")
+            else:
+                logger.success(
+                    f"Self-update launcher directory preference saved: {install_dir} "
+                    "(must match the existing Unix installation)"
+                )
         except ValueError as exc:
             logger.error(str(exc))
             sys.exit(1)
@@ -636,7 +643,13 @@ def get(key):
 
             value = get_self_update_install_dir()
             if value is None:
-                click.echo("self-update.install-dir: Not set (using installer default)")
+                if self_update_command._is_windows_platform():
+                    click.echo("self-update.install-dir: Not set (using installer default)")
+                else:
+                    click.echo(
+                        "self-update.install-dir: Not set "
+                        "(preserving the detected Unix installation)"
+                    )
             else:
                 click.echo(f"self-update.install-dir: {value}")
             return
@@ -766,7 +779,13 @@ def unset(key):
         from ..config import unset_self_update_install_dir
 
         unset_self_update_install_dir()
-        logger.success("Self-update install directory removed (will use installer default)")
+        if self_update_command._is_windows_platform():
+            logger.success("Self-update install directory removed (will use installer default)")
+        else:
+            logger.success(
+                "Self-update launcher directory preference removed "
+                "(will preserve the detected Unix installation)"
+            )
         return
 
     if key == "mcp-registry-url":

{apm_cli-0.29.1 → apm_cli-0.30.0}/src/apm_cli/commands/prune.py

@@ -241,6 +241,7 @@ def prune(ctx, dry_run):
             return
 
         removed_count = 0
+        failed_count = 0
         removed_packages: list[str] = []
         pruned_keys = list(missing_orphaned_keys)
         pruned_key_set = set(pruned_keys)
@@ -263,6 +264,7 @@ def prune(ctx, dry_run):
                         pruned_key_set.add(dep_key)
                 deleted_pkg_paths.append(pkg_path)
             except Exception as e:
+                failed_count += 1
                 logger.error(f"Failed to remove {org_repo_name}: {e}")
 
         BaseIntegrator.cleanup_empty_parents(deleted_pkg_paths, stop_at=apm_modules_dir)
@@ -397,6 +399,17 @@ def prune(ctx, dry_run):
                     "stale -- run 'apm install' to rebuild hook configuration."
                 )
 
+        if failed_count:
+            logger.error(
+                f"Prune incomplete: removed {removed_count} orphaned package(s); "
+                f"failed to remove {failed_count} package(s)."
+            )
+            logger.error_detail(
+                "Filesystem cleanup may be partial. Resolve the removal errors, "
+                "then rerun 'apm prune'."
+            )
+            sys.exit(1)
+
         if removed_count > 0:
             message = f"Pruned {removed_count} orphaned package(s)"
             if owner_violations:

{apm_cli-0.29.1 → apm_cli-0.30.0}/src/apm_cli/commands/self_update.py

@@ -170,7 +170,9 @@ def get_latest_version_for_self_update(channel: str) -> str | None:
     """Return the latest version for a supported self-update channel."""
     from ..utils.version_checker import get_latest_version_from_github
 
-    return get_latest_version_from_github(include_prerelease=(channel == "prerelease"))
+    return get_latest_version_from_github(
+        include_prerelease=(channel == "prerelease"), raise_errors=True
+    )
 
 
 def _build_self_update_installer_env(
@@ -194,6 +196,11 @@ def _build_self_update_installer_env(
     if _ENV_SELF_UPDATE_CHANNEL not in env:
         env[_ENV_SELF_UPDATE_CHANNEL] = channel
     env[_ENV_VERSION] = release.tag
+    if not _is_windows_platform():
+        # Pass identity, not a second destination policy: install.sh owns routing.
+        env["APM_SELF_UPDATE_SOURCE"] = os.path.abspath(
+            sys.executable if getattr(sys, "frozen", False) else sys.argv[0]
+        )
     return env
 
 
@@ -266,7 +273,13 @@ def self_update(check: bool) -> None:
             sys.exit(1)
 
         # Check for latest version
-        latest_version = get_latest_version_for_self_update(_channel)
+        from ..utils.version_checker import ReleaseMetadataError
+
+        try:
+            latest_version = get_latest_version_for_self_update(_channel)
+        except ReleaseMetadataError as exc:
+            logger.error(str(exc))
+            sys.exit(1)
 
         if not latest_version:
             if _pinned:
@@ -352,7 +365,7 @@ def self_update(check: bool) -> None:
 
             # Note: We don't capture output so the installer can prompt when needed.
             # Sanitise the environment so the installer (and the system binaries
-            # it spawns -- curl, tar, sudo) do not inherit the PyInstaller
+            # it spawns -- curl and tar) do not inherit the PyInstaller
             # bootloader's LD_LIBRARY_PATH / DYLD_* overrides, which would
             # otherwise redirect system linkers at this binary's bundled
             # _internal directory.  See issue #894.
@@ -373,7 +386,8 @@ def self_update(check: bool) -> None:
                 logger.success(
                     f"Successfully updated to version {release.version}!",
                 )
-                logger.progress("Please restart your terminal or run 'apm --version' to verify")
+                if _is_windows_platform():
+                    logger.progress("Please restart your terminal or run 'apm --version' to verify")
             else:
                 logger.error("Installation failed - see output above for details")
                 sys.exit(1)