apm-cli 0.24.1__tar.gz → 0.25.0__tar.gz

{apm_cli-0.24.1/src/apm_cli.egg-info → apm_cli-0.25.0}/PKG-INFO

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

{apm_cli-0.24.1 → apm_cli-0.25.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "apm-cli"
-version = "0.24.1"
+version = "0.25.0"
 description = "MCP configuration tool"
 readme = "README.md"
 requires-python = ">=3.10"

{apm_cli-0.24.1 → apm_cli-0.25.0}/src/apm_cli/adapters/client/base.py

@@ -210,6 +210,19 @@ class MCPClientAdapter(ABC):
             return self._project_root
         return Path(os.getcwd())
 
+    def render_server_config(self, server_info: dict) -> dict:
+        """Render one native server entry for exact baseline comparisons."""
+        rendered = self._format_server_config(
+            server_info,
+            env_overrides={},
+            runtime_vars={},
+        )
+        if isinstance(rendered, tuple):
+            rendered = rendered[0]
+        if not isinstance(rendered, dict):
+            raise ValueError("Adapter did not produce a native MCP server mapping")
+        return rendered
+
     @abstractmethod
     def get_config_path(self):
         """Get the path to the MCP configuration file."""

{apm_cli-0.24.1 → apm_cli-0.25.0}/src/apm_cli/bundle/packer.py

@@ -93,7 +93,9 @@ def pack_bundle(
         package = APMPackage.from_apm_yml(apm_yml_path)
         pkg_name = package.name
         pkg_version = package.version or "0.0.0"
-        config_target = package.target
+        from apm_cli.models.apm_package import package_target_selection
+
+        config_target = package_target_selection(package)
 
         # HYBRID author guard: apm.yml.description and SKILL.md
         # description serve different consumers (human-facing CLI/search
@@ -141,7 +143,7 @@ def pack_bundle(
         # List from CLI (e.g. --target claude,copilot) passes through directly
         effective_target = target
     elif isinstance(config_target, list) and target is None:
-        # List from apm.yml target: [claude, copilot]
+        # Canonical list from either apm.yml target spelling.
         effective_target = config_target
     else:
         effective_target, _reason = detect_target(

{apm_cli-0.24.1 → apm_cli-0.25.0}/src/apm_cli/bundle/plugin_exporter.py

@@ -30,8 +30,10 @@ from ..utils.archive import (
 )
 from ..utils.console import _rich_warning
 from ..utils.path_security import PathTraversalError, ensure_path_within, safe_rmtree
+from ..utils.paths import portable_relpath
 from .attest import verify_attested_file
 from .packer import PackResult
+from .plugin_layout import PLUGIN_ROOT_DIRS, find_plugin_root_sources
 
 # ---------------------------------------------------------------------------
 # Path helpers
@@ -125,11 +127,49 @@ def _collect_root_plugin_components(project_root: Path) -> list[tuple[Path, str]
     ``skills/``, etc. at the repo root) have their files picked up here.
     """
     components: list[tuple[Path, str]] = []
-    for dir_name in ("agents", "skills", "commands", "instructions", "extensions"):
+    for dir_name in PLUGIN_ROOT_DIRS:
+        if dir_name == "hooks":
+            continue
         _collect_recursive(project_root / dir_name, dir_name, components)
     return components
 
 
+def _emit_pack_warning(message: str, logger=None) -> None:
+    """Send a pack warning through the command logger when available."""
+    if logger:
+        logger.warning(message)
+    else:
+        _rich_warning(message, symbol="warning")
+
+
+def _warn_skipped_root_components(project_root: Path, logger=None) -> None:
+    """Explain why plugin-native root sources are not packed."""
+    for source in find_plugin_root_sources(project_root):
+        if source == "hooks.json":
+            message = (
+                "Skipping root-level hooks.json because .apm/ is present. "
+                "Move publishable hook configuration to .apm/hooks/ or remove "
+                "hooks.json to silence this warning."
+            )
+        else:
+            message = (
+                f"Skipping root-level {source}/ because .apm/ is present. "
+                f"Move publishable files to .apm/{source}/ or remove {source}/ "
+                "to silence this warning."
+            )
+        _emit_pack_warning(message, logger)
+
+
+def _warn_no_local_primitives(logger=None) -> None:
+    """Explain how to recover from an empty APM-native source layout."""
+    _emit_pack_warning(
+        "No local primitives found. Expected content under .apm/. "
+        "Move plugin-native content into .apm/, or remove .apm/ to restore "
+        "root convention discovery.",
+        logger,
+    )
+
+
 def _collect_bare_skill(
     install_path: Path,
     dep: "LockedDependency",
@@ -178,7 +218,7 @@ def _collect_flat(
     rename=None,
 ) -> None:
     """Add every regular non-symlink file directly inside *src_dir*."""
-    if not src_dir.is_dir():
+    if src_dir.is_symlink() or not src_dir.is_dir():
         return
     for f in sorted(src_dir.iterdir()):
         if f.is_file() and not f.is_symlink():
@@ -194,7 +234,7 @@ def _collect_recursive(
     rename=None,
 ) -> None:
     """Add every regular non-symlink file under *src_dir*, preserving hierarchy."""
-    if not src_dir.is_dir():
+    if src_dir.is_symlink() or not src_dir.is_dir():
         return
     for f in sorted(src_dir.rglob("*")):
         if not f.is_file() or f.is_symlink():
@@ -483,6 +523,76 @@ def _plugin_rel_for_deployed_path(
     return PurePosixPath(*plugin_parts).as_posix()
 
 
+def _collect_explicit_local_components(
+    project_root: Path,
+    includes: list[str],
+) -> tuple[list[tuple[Path, str]], dict]:
+    """Collect only explicitly listed local paths and validate each path."""
+    components: list[tuple[Path, str]] = []
+    hooks: dict = {}
+    for declared_path in includes:
+        parts = _deployed_path_parts(declared_path)
+        candidate = project_root.joinpath(*parts)
+        if candidate.is_symlink():
+            raise ValueError(
+                f"includes path {declared_path!r} is a symlink. "
+                "Replace it with a regular file or directory."
+            )
+        try:
+            source = ensure_path_within(candidate, project_root)
+        except PathTraversalError as exc:
+            raise ValueError(
+                f"includes path {declared_path!r} escapes the project root. "
+                "Fix the path in apm.yml."
+            ) from exc
+        if not source.exists():
+            raise ValueError(
+                f"includes path {declared_path!r} does not exist. "
+                "Fix the path in apm.yml or create it."
+            )
+        entries = [source] if source.is_file() else sorted(source.rglob("*"))
+        for entry in entries:
+            if entry.is_symlink():
+                raise ValueError(
+                    f"Symlink found inside includes path {declared_path!r}: "
+                    f"{entry.name}. Remove the symlink or list a regular path."
+                )
+        for file_path in (entry for entry in entries if entry.is_file()):
+            try:
+                file_path = ensure_path_within(file_path, project_root)
+            except PathTraversalError as exc:
+                raise ValueError(
+                    f"A file inside includes path {declared_path!r} escapes the "
+                    "project root. Remove the symlink or fix the path in apm.yml."
+                ) from exc
+            repo_relative = portable_relpath(file_path, project_root)
+            is_hook = (
+                repo_relative == "hooks.json"
+                or repo_relative.startswith("hooks/")
+                or repo_relative.startswith(".apm/hooks/")
+            )
+            if is_hook:
+                try:
+                    hook_data = json.loads(file_path.read_text(encoding="utf-8"))
+                except (OSError, ValueError, RecursionError) as exc:
+                    raise ValueError(
+                        f"Explicit hook include is not valid JSON: {repo_relative}"
+                    ) from exc
+                if not isinstance(hook_data, dict):
+                    raise ValueError(
+                        f"Explicit hook include must contain a JSON object: {repo_relative}"
+                    )
+                _deep_merge(hooks, hook_data, overwrite=False)
+                continue
+            plugin_relative = _plugin_rel_for_deployed_path(repo_relative, None)
+            if plugin_relative is None:
+                raise ValueError(
+                    f"Explicit include path is not a packable primitive: {repo_relative}"
+                )
+            components.append((file_path, plugin_relative))
+    return components, hooks
+
+
 def _verify_attested_hash(
     source: Path,
     project_root: Path,
@@ -765,16 +875,34 @@ def export_plugin_bundle(
 
             _merge_file_map(file_map, dep_components, dep_name, force, collisions)
 
-    # 6. Collect own components (.apm/ and root-level)
+    # 6. Collect own components according to the local source authority.
     own_apm_dir = project_root / ".apm"
-    own_components = _collect_apm_components(own_apm_dir)
-    own_components.extend(_collect_root_plugin_components(project_root))
+    if isinstance(package.includes, list):
+        own_components, root_hooks = _collect_explicit_local_components(
+            project_root,
+            package.includes,
+        )
+    else:
+        own_components = _collect_apm_components(own_apm_dir)
+        root_hooks = _collect_hooks_from_apm(own_apm_dir)
+        if own_apm_dir.is_dir():
+            _warn_skipped_root_components(project_root, logger)
+        else:
+            own_components.extend(_collect_root_plugin_components(project_root))
+            root_hooks_top = _collect_hooks_from_root(project_root)
+            _deep_merge(root_hooks, root_hooks_top, overwrite=False)
+
+    if (
+        not isinstance(package.includes, list)
+        and own_apm_dir.is_dir()
+        and not own_components
+        and not root_hooks
+    ):
+        _warn_no_local_primitives(logger)
+
     _merge_file_map(file_map, own_components, pkg_name, force, collisions)
 
     # Hooks -- root package wins on key collision
-    root_hooks = _collect_hooks_from_apm(own_apm_dir)
-    root_hooks_top = _collect_hooks_from_root(project_root)
-    _deep_merge(root_hooks, root_hooks_top, overwrite=False)
     _deep_merge(merged_hooks, root_hooks, overwrite=True)
 
     # MCP -- root package wins on server-name collision

apm_cli-0.25.0/src/apm_cli/bundle/plugin_layout.py

@@ -0,0 +1,24 @@
+"""Plugin-native source-layout conventions."""
+
+from pathlib import Path
+
+PLUGIN_ROOT_DIRS = (
+    "agents",
+    "skills",
+    "commands",
+    "instructions",
+    "extensions",
+    "hooks",
+)
+
+
+def find_plugin_root_sources(project_root: Path) -> list[str]:
+    """Return plugin-native root sources that exist."""
+    sources = [
+        name
+        for name in PLUGIN_ROOT_DIRS
+        if (project_root / name).is_dir() and not (project_root / name).is_symlink()
+    ]
+    if (project_root / "hooks.json").is_file():
+        sources.append("hooks.json")
+    return sources

{apm_cli-0.24.1 → apm_cli-0.25.0}/src/apm_cli/cache/http_cache.py

@@ -70,6 +70,7 @@ class HttpCache:
         self._cache_dir.mkdir(parents=True, exist_ok=True)
         os.chmod(str(self._cache_dir), 0o700)
         cleanup_incomplete(self._cache_dir)
+        self._tracked_size: int | None = None
 
     def get(self, url: str, headers: dict[str, str] | None = None) -> CacheEntry | None:
         """Look up a cached response for *url*.
@@ -233,6 +234,13 @@ class HttpCache:
         with contextlib.suppress(OSError):
             os.utime(str(entry_path), None)
 
+        # Update tracked size with an upper-bound estimate. Over-counting is
+        # intentional: it triggers a real scan sooner, correcting the estimate,
+        # rather than delaying eviction. The scan in _enforce_size_cap resets
+        # _tracked_size to the real total once it runs.
+        if self._tracked_size is not None:
+            self._tracked_size += len(body) + 512  # body + metadata upper-bound estimate
+
         # Enforce size cap
         self._enforce_size_cap()
 
@@ -321,10 +329,20 @@ class HttpCache:
         return 300.0
 
     def _enforce_size_cap(self) -> None:
-        """Evict LRU entries if total cache size exceeds the cap."""
+        """Evict LRU entries if total cache size exceeds the cap.
+
+        Uses a tracked size estimate to skip the full directory scan
+        when we are clearly under the cap (fast path). Falls back to a
+        full scan when the tracked size exceeds the limit or has not
+        been computed yet.
+        """
         if not self._cache_dir.is_dir():
             return
 
+        # Fast path: if we have a tracked size and it is under cap, skip scan
+        if self._tracked_size is not None and self._tracked_size <= MAX_HTTP_CACHE_BYTES:
+            return
+
         entries: list[tuple[float, str, int]] = []
         total_size = 0
 
@@ -343,6 +361,8 @@ class HttpCache:
             except OSError:
                 continue
 
+        self._tracked_size = total_size
+
         if total_size <= MAX_HTTP_CACHE_BYTES:
             return
 
@@ -356,3 +376,5 @@ class HttpCache:
                 break
             robust_rmtree(Path(path), ignore_errors=True)
             total_size -= size
+
+        self._tracked_size = total_size

{apm_cli-0.24.1 → apm_cli-0.25.0}/src/apm_cli/cli.py

@@ -64,6 +64,14 @@ _CLI_EPILOG = (
 )
 
 
+class _OutputModeGroup(click.Group):
+    """Capture full argv so root output mode precedes subcommand callbacks."""
+
+    def parse_args(self, ctx: click.Context, args: list[str]) -> list[str]:
+        ctx.meta["apm_raw_args"] = tuple(args)
+        return super().parse_args(ctx, args)
+
+
 def _configure_logging(verbose: bool = False) -> None:
     """Configure stdlib logging for the ``apm_cli`` package.
 
@@ -102,11 +110,17 @@ def _configure_logging(verbose: bool = False) -> None:
     # Install secret-redaction filter (idempotent: skip if already present).
     from apm_cli.core.auth import SecretRedactionFilter
 
-    if not any(isinstance(f, SecretRedactionFilter) for f in apm_logger.filters):
-        apm_logger.addFilter(SecretRedactionFilter())
+    handlers = {
+        *logging.getLogger().handlers,
+        *apm_logger.handlers,
+    }
+    for handler in handlers:
+        if not any(isinstance(f, SecretRedactionFilter) for f in handler.filters):
+            handler.addFilter(SecretRedactionFilter())
 
 
 @click.group(
+    cls=_OutputModeGroup,
     help="Agent Package Manager (APM): The package manager for AI-Native Development",
     epilog=_CLI_EPILOG,
 )
@@ -130,6 +144,11 @@ def cli(ctx, verbose: bool) -> None:
     """Main entry point for the APM CLI."""
     ctx.ensure_object(dict)
     ctx.obj["verbose"] = verbose
+    from apm_cli.core.output_mode import configure_output_mode, detect_output_mode
+
+    output_mode = detect_output_mode(ctx.meta.get("apm_raw_args", sys.argv[1:]))
+    configure_output_mode(output_mode)
+    ctx.obj["output_mode"] = output_mode
 
     if verbose:
         # Upgrade to DEBUG when the flag is set; env-var path runs in main().

{apm_cli-0.24.1 → apm_cli-0.25.0}/src/apm_cli/commands/_helpers.py

@@ -474,7 +474,7 @@ def _check_and_notify_updates():
             _rich_echo(get_update_hint_message(), color="yellow", bold=True)
 
             # Add a blank line for visual separation
-            click.echo()
+            _rich_echo("")
     except Exception:
         # Silently fail - version checking should never block CLI usage
         pass
@@ -706,12 +706,14 @@ def _create_minimal_apm_yml(config, plugin=False, target_path=None):
     content = out_file.read_text(encoding="utf-8")
 
     if "targets" in apm_yml_data:
+        from apm_cli.core.target_catalog import manifest_target_names
+
         # Insert comment before the targets: line
+        accepted_targets = ", ".join(sorted(manifest_target_names()))
         targets_comment = (
             "# Which agent platforms to deploy to.\n"
             "# Resolution order: --target flag > this field > auto-detect from filesystem.\n"
-            "# Accepted values: vscode, agents, copilot, claude, cursor, opencode, codex,\n"
-            "# gemini, antigravity, windsurf, kiro, agent-skills, all\n"
+            f"# Accepted values: {accepted_targets}\n"
         )
         content = content.replace("targets:", targets_comment + "targets:", 1)
     else:

{apm_cli-0.24.1 → apm_cli-0.25.0}/src/apm_cli/commands/audit.py

@@ -535,7 +535,7 @@ def _audit_ci_gate(
     # Resolve policy source: explicit --policy wins; otherwise mirror
     # install's auto-discovery (closes #827) so CI catches sideloaded
     # files via unmanaged-files checks. --no-policy skips discovery.
-    from ..policy.discovery import discover_policy, discover_policy_with_chain
+    from ..policy.discovery import discover_policy_with_chain
     from ..policy.project_config import (
         read_project_fetch_failure_default,
     )
@@ -543,7 +543,7 @@ def _audit_ci_gate(
     fetch_result = None
     auto_discovered = False
     if policy_source and (not fail_fast or ci_result.passed):
-        fetch_result = discover_policy(
+        fetch_result = discover_policy_with_chain(
             cfg.project_root,
             policy_override=policy_source,
             no_cache=no_cache,
@@ -576,6 +576,7 @@ def _audit_ci_gate(
             "malformed",
             "cache_miss_fetch_fail",
             "garbage_response",
+            "incomplete_chain",
         )
         no_policy_outcomes = ("absent", "no_git_remote", "empty")
 
@@ -595,7 +596,7 @@ def _audit_ci_gate(
             source = fetch_result.source
             err_text = fetch_result.error or fetch_result.fetch_error or fetch_result.outcome
             cause = _audit_outcome_cause(fetch_result.outcome, source, err_text)
-            if project_default == "block":
+            if fetch_result.outcome == "incomplete_chain" or project_default == "block":
                 click.echo(
                     f"[x] {cause} (policy.fetch_failure_default=block)",
                     err=True,
@@ -858,10 +859,16 @@ def _audit_content_scan(
             else:
                 logger.start("Scanning all installed packages...")
 
-            findings_by_file, files_scanned = scan_lockfile_packages(
-                project_root,
-                package_filter=package,
-            )
+            from apm_cli.deps.lockfile import LockfileFormatError
+
+            try:
+                findings_by_file, files_scanned = scan_lockfile_packages(
+                    project_root,
+                    package_filter=package,
+                )
+            except LockfileFormatError as exc:
+                logger.error(f"Cannot audit invalid apm.lock.yaml: {exc}")
+                sys.exit(1)
 
             if files_scanned == 0 and not external:
                 if package: