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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: apm-cli
-Version: 0.32.0
+Version: 0.34.0
 Summary: MCP configuration tool
 Author-email: Daniel Meppiel <user@example.com>
 License: MIT License
@@ -78,7 +78,7 @@ Think `package.json`, `requirements.txt`, or `Cargo.toml` — but for AI agent c
 
 GitHub Copilot | Claude Code | Grok Build | Cursor | OpenCode | Codex | Gemini | Windsurf | Kiro
 
-**[Documentation](https://microsoft.github.io/apm/)** · **[Quick Start](https://microsoft.github.io/apm/getting-started/quick-start/)** · **[CLI Reference](https://microsoft.github.io/apm/reference/cli-commands/)** · **[Roadmap](https://github.com/orgs/microsoft/projects/2304/views/5)**
+**[Documentation](https://microsoft.github.io/apm/)** · **[Quick Start](https://microsoft.github.io/apm/quickstart/)** · **[CLI Reference](https://microsoft.github.io/apm/reference/)** · **[Roadmap](https://github.com/orgs/microsoft/projects/2304/views/5)**
 
 ---
 
@@ -140,11 +140,11 @@ One command, no configuration -- VS Code and GitHub Copilot read the file automa
 One `apm.yml` describes every primitive your agents need — instructions, skills, prompts, agents, hooks, plugins, MCP servers — and `apm install` reproduces the exact same setup across every client on every machine. `apm.lock.yaml` pins the resolved tree the way `package-lock.json` does for npm.
 
 - **[One manifest for everything](https://microsoft.github.io/apm/reference/primitive-types/)** -- declared once, deployed across Copilot, Claude, Grok Build, Cursor, OpenCode, Codex, Gemini, Windsurf, Kiro
-- **[Install from anywhere](https://microsoft.github.io/apm/guides/dependencies/)** — GitHub, GitLab, Bitbucket, Azure DevOps, GitHub Enterprise, Gitea, Gogs, any git host
-- **[Transitive dependencies](https://microsoft.github.io/apm/guides/dependencies/)** — packages can depend on packages; APM resolves the full tree
-- **[Author plugins](https://microsoft.github.io/apm/guides/plugins/)** — build Copilot, Claude, and Cursor plugins with dependency management, then export standard `plugin.json`
-- **[Marketplaces](https://microsoft.github.io/apm/guides/marketplaces/)** — install plugins from curated registries in one command, deployed across all targets and locked
-- **[Pack & distribute](https://microsoft.github.io/apm/guides/pack-distribute/)** — `apm pack` bundles your configuration as a zipped package or a standalone plugin
+- **[Install from anywhere](https://microsoft.github.io/apm/consumer/install-packages/)** — GitHub, GitLab, Bitbucket, Azure DevOps, GitHub Enterprise, Gitea, Gogs, any git host
+- **[Transitive dependencies](https://microsoft.github.io/apm/consumer/install-packages/#transitive-dependencies-and-the-lockfile)** — packages can depend on packages; APM resolves the full tree
+- **[Author plugins](https://microsoft.github.io/apm/producer/)** — build Copilot, Claude, and Cursor plugins with dependency management, then export standard `plugin.json`
+- **[Marketplaces](https://microsoft.github.io/apm/consumer/installing-from-marketplaces/)** — install plugins from curated registries in one command, deployed across all targets and locked
+- **[Pack & distribute](https://microsoft.github.io/apm/producer/pack-a-bundle/)** — `apm pack` bundles your configuration as a zipped package or a standalone plugin
 - **[CI/CD ready](https://github.com/microsoft/apm-action)** — GitHub Action for automated workflows
 
 ### 2. Secure by default
@@ -152,10 +152,10 @@ One `apm.yml` describes every primitive your agents need — instructions, skill
 Agent context is executable in effect — a prompt is a program for an LLM. APM treats it that way. Every install scans for hidden Unicode that can hijack agent behavior; the lockfile pins integrity hashes; transitive MCP servers are gated by trust prompts.
 
 - **[Content security](https://microsoft.github.io/apm/enterprise/security/)** — `apm install` blocks compromised packages before agents read them; `apm audit` runs the same checks on demand
-- **[Lockfile integrity](https://microsoft.github.io/apm/enterprise/governance/)** — `apm.lock` records resolved sources and content hashes for full provenance
+- **[Lockfile integrity](https://microsoft.github.io/apm/reference/lockfile-spec/)** — `apm.lock` records resolved sources and content hashes for full provenance
 - **[SBOM export](https://microsoft.github.io/apm/reference/cli/lock/)** — `apm lock export --format cyclonedx|spdx` emits a standard inventory of what reached disk, straight from the lockfile — provenance for procurement, not a compliance attestation
-- **[Drift detection](https://microsoft.github.io/apm/guides/drift-detection/)** — `apm audit` rebuilds your agent context in scratch and diffs it against your working tree to catch hand-edits before they ship
-- **[MCP trust boundaries](https://microsoft.github.io/apm/guides/mcp-servers/)** — transitive MCP servers require explicit consent
+- **[Drift detection](https://microsoft.github.io/apm/enterprise/drift-detection/)** — `apm audit` rebuilds your agent context in scratch and diffs it against your working tree to catch hand-edits before they ship
+- **[MCP trust boundaries](https://microsoft.github.io/apm/consumer/install-mcp-servers/)** — transitive MCP servers require explicit consent
 
 ### 3. Governed by policy
 
@@ -244,7 +244,7 @@ Or add an MCP server (wired into Copilot, Claude, Cursor, Codex, OpenCode, Gemin
 apm install --mcp io.github.github/github-mcp-server --transport http   # connects over HTTPS
 ```
 
-See the **[Getting Started guide](https://microsoft.github.io/apm/getting-started/quick-start/)** for the full walkthrough.
+See the **[Getting Started guide](https://microsoft.github.io/apm/quickstart/)** for the full walkthrough.
 
 ## Works with agentrc
 

{apm_cli-0.32.0 → apm_cli-0.34.0}/README.md

@@ -6,7 +6,7 @@ Think `package.json`, `requirements.txt`, or `Cargo.toml` — but for AI agent c
 
 GitHub Copilot | Claude Code | Grok Build | Cursor | OpenCode | Codex | Gemini | Windsurf | Kiro
 
-**[Documentation](https://microsoft.github.io/apm/)** · **[Quick Start](https://microsoft.github.io/apm/getting-started/quick-start/)** · **[CLI Reference](https://microsoft.github.io/apm/reference/cli-commands/)** · **[Roadmap](https://github.com/orgs/microsoft/projects/2304/views/5)**
+**[Documentation](https://microsoft.github.io/apm/)** · **[Quick Start](https://microsoft.github.io/apm/quickstart/)** · **[CLI Reference](https://microsoft.github.io/apm/reference/)** · **[Roadmap](https://github.com/orgs/microsoft/projects/2304/views/5)**
 
 ---
 
@@ -68,11 +68,11 @@ One command, no configuration -- VS Code and GitHub Copilot read the file automa
 One `apm.yml` describes every primitive your agents need — instructions, skills, prompts, agents, hooks, plugins, MCP servers — and `apm install` reproduces the exact same setup across every client on every machine. `apm.lock.yaml` pins the resolved tree the way `package-lock.json` does for npm.
 
 - **[One manifest for everything](https://microsoft.github.io/apm/reference/primitive-types/)** -- declared once, deployed across Copilot, Claude, Grok Build, Cursor, OpenCode, Codex, Gemini, Windsurf, Kiro
-- **[Install from anywhere](https://microsoft.github.io/apm/guides/dependencies/)** — GitHub, GitLab, Bitbucket, Azure DevOps, GitHub Enterprise, Gitea, Gogs, any git host
-- **[Transitive dependencies](https://microsoft.github.io/apm/guides/dependencies/)** — packages can depend on packages; APM resolves the full tree
-- **[Author plugins](https://microsoft.github.io/apm/guides/plugins/)** — build Copilot, Claude, and Cursor plugins with dependency management, then export standard `plugin.json`
-- **[Marketplaces](https://microsoft.github.io/apm/guides/marketplaces/)** — install plugins from curated registries in one command, deployed across all targets and locked
-- **[Pack & distribute](https://microsoft.github.io/apm/guides/pack-distribute/)** — `apm pack` bundles your configuration as a zipped package or a standalone plugin
+- **[Install from anywhere](https://microsoft.github.io/apm/consumer/install-packages/)** — GitHub, GitLab, Bitbucket, Azure DevOps, GitHub Enterprise, Gitea, Gogs, any git host
+- **[Transitive dependencies](https://microsoft.github.io/apm/consumer/install-packages/#transitive-dependencies-and-the-lockfile)** — packages can depend on packages; APM resolves the full tree
+- **[Author plugins](https://microsoft.github.io/apm/producer/)** — build Copilot, Claude, and Cursor plugins with dependency management, then export standard `plugin.json`
+- **[Marketplaces](https://microsoft.github.io/apm/consumer/installing-from-marketplaces/)** — install plugins from curated registries in one command, deployed across all targets and locked
+- **[Pack & distribute](https://microsoft.github.io/apm/producer/pack-a-bundle/)** — `apm pack` bundles your configuration as a zipped package or a standalone plugin
 - **[CI/CD ready](https://github.com/microsoft/apm-action)** — GitHub Action for automated workflows
 
 ### 2. Secure by default
@@ -80,10 +80,10 @@ One `apm.yml` describes every primitive your agents need — instructions, skill
 Agent context is executable in effect — a prompt is a program for an LLM. APM treats it that way. Every install scans for hidden Unicode that can hijack agent behavior; the lockfile pins integrity hashes; transitive MCP servers are gated by trust prompts.
 
 - **[Content security](https://microsoft.github.io/apm/enterprise/security/)** — `apm install` blocks compromised packages before agents read them; `apm audit` runs the same checks on demand
-- **[Lockfile integrity](https://microsoft.github.io/apm/enterprise/governance/)** — `apm.lock` records resolved sources and content hashes for full provenance
+- **[Lockfile integrity](https://microsoft.github.io/apm/reference/lockfile-spec/)** — `apm.lock` records resolved sources and content hashes for full provenance
 - **[SBOM export](https://microsoft.github.io/apm/reference/cli/lock/)** — `apm lock export --format cyclonedx|spdx` emits a standard inventory of what reached disk, straight from the lockfile — provenance for procurement, not a compliance attestation
-- **[Drift detection](https://microsoft.github.io/apm/guides/drift-detection/)** — `apm audit` rebuilds your agent context in scratch and diffs it against your working tree to catch hand-edits before they ship
-- **[MCP trust boundaries](https://microsoft.github.io/apm/guides/mcp-servers/)** — transitive MCP servers require explicit consent
+- **[Drift detection](https://microsoft.github.io/apm/enterprise/drift-detection/)** — `apm audit` rebuilds your agent context in scratch and diffs it against your working tree to catch hand-edits before they ship
+- **[MCP trust boundaries](https://microsoft.github.io/apm/consumer/install-mcp-servers/)** — transitive MCP servers require explicit consent
 
 ### 3. Governed by policy
 
@@ -172,7 +172,7 @@ Or add an MCP server (wired into Copilot, Claude, Cursor, Codex, OpenCode, Gemin
 apm install --mcp io.github.github/github-mcp-server --transport http   # connects over HTTPS
 ```
 
-See the **[Getting Started guide](https://microsoft.github.io/apm/getting-started/quick-start/)** for the full walkthrough.
+See the **[Getting Started guide](https://microsoft.github.io/apm/quickstart/)** for the full walkthrough.
 
 ## Works with agentrc
 

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "apm-cli"
-version = "0.32.0"
+version = "0.34.0"
 description = "MCP configuration tool"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -205,12 +205,14 @@ markers = [
     "slow: marks tests as slow running tests",
     "benchmark: marks performance benchmark tests (deselected by default, run with -m benchmark)",
     "windows_compat: load-bearing cross-platform regression contract family (CRLF-safe atomic writes, portable path formatting, git-executable resolution, socket/thread shutdown); runs on every OS and is additionally selected by the PR-time Windows Compatibility Gate -- NOT a requires_windows skip-gate, do not use requires_windows for this",
+    "trusted_executable: native trusted git/gh discovery and real consumer regressions; additionally selected on Windows Python 3.10 and 3.11",
     "requires_e2e_mode: requires APM_E2E_TESTS=1",
     "requires_github_token: requires GITHUB_APM_PAT or GITHUB_TOKEN",
     "requires_ado_pat: requires ADO_APM_PAT",
     "requires_ado_bearer: requires az CLI logged in + APM_TEST_ADO_BEARER=1",
     "requires_network_integration: requires APM_RUN_INTEGRATION_TESTS=1",
     "requires_windows: requires a Windows host",
+    "requires_windows_native_standard_user: requires the disposable Windows runner's verified non-admin token and symlink denial",
     "requires_apm_binary: requires built apm binary on PATH (or APM_BINARY_PATH)",
     "requires_runtime_codex: requires codex runtime installed",
     "requires_runtime_copilot: requires GitHub Copilot CLI runtime installed",

{apm_cli-0.32.0 → apm_cli-0.34.0}/src/apm_cli/adapters/client/base.py

@@ -1,5 +1,6 @@
 """Base adapter interface for MCP clients."""
 
+import json
 import os
 import re
 from abc import ABC, abstractmethod
@@ -8,7 +9,9 @@ from pathlib import Path
 from typing import Any, ClassVar
 
 from ...models.dependency.mcp import _EXTRA_DENYLIST, TrustedEnvLiteral
+from ...utils.atomic_io import atomic_write_text
 from ...utils.console import _rich_error, _rich_warning
+from ...utils.path_security import has_symlink_component
 
 _INPUT_VAR_RE = re.compile(r"\$\{input:([^}]+)\}")
 
@@ -396,6 +399,71 @@ class MCPClientAdapter(ABC):
         """Get the current MCP configuration."""
         pass
 
+    def validate_config_for_install(self) -> bool:
+        """Allow adapters to refuse unsafe configs before existing-server shortcuts."""
+        return True
+
+    def _read_json_config_for_update(self, config_path: Path) -> dict | None:
+        """Return the JSON object at *config_path* before a merge-and-write.
+
+        A missing or blank file yields ``{}``.  Returns ``None`` after a
+        warning when rewriting the file could lose data, so the caller skips
+        the write: the existing content is not a JSON object (for example
+        JSONC comments), or a user-scope path runs through a symlink, which
+        stale cleanup refuses to rewrite later.
+        """
+        if self.user_scope and has_symlink_component(Path.home(), config_path):
+            _rich_warning(
+                f"Skipped {config_path}: APM does not write MCP config through "
+                "symlinks. Replace the symlink or configure this server manually.",
+                symbol="warning",
+            )
+            return None
+        try:
+            raw = config_path.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            return {}
+        except (OSError, UnicodeError) as exc:
+            _rich_warning(
+                f"Could not read {config_path}: {exc} -- skipping config write; "
+                "fix the file's permissions or encoding, or add this server manually",
+                symbol="warning",
+            )
+            return None
+        if not raw.strip():
+            return {}
+        try:
+            config = json.loads(raw)
+        except json.JSONDecodeError:
+            config = None
+        if not isinstance(config, dict):
+            _rich_warning(
+                f"Could not parse {config_path} as a JSON object -- skipping config "
+                "write to avoid data loss (comments and trailing commas are not "
+                "preserved); fix the file or add this server manually",
+                symbol="warning",
+            )
+            return None
+        if self.mcp_servers_key in config and not isinstance(config[self.mcp_servers_key], dict):
+            _rich_warning(
+                f"Could not parse {config_path}: {self.mcp_servers_key} must be "
+                "a JSON object -- skipping config write to avoid data loss; "
+                "fix the file or add this server manually",
+                symbol="warning",
+            )
+            return None
+        return config
+
+    @staticmethod
+    def _write_json_config(config_path: Path, config: dict) -> None:
+        """Atomically write *config* as JSON and keep the file owner-only.
+
+        Entries can carry env values resolved at install time.
+        """
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        atomic_write_text(config_path, json.dumps(config, indent=2), new_file_mode=0o600)
+        os.chmod(config_path, 0o600)
+
     @abstractmethod
     def configure_mcp_server(
         self,
@@ -1424,7 +1492,7 @@ class MCPClientAdapter(ABC):
 
         Args:
             config: Mutable config dict updated in place.
-            remote: Registry remote entry (may contain a ``"headers"`` list).
+            remote: Registry remote entry (headers may be records or a mapping).
             server_info: Registry server metadata used for name / URL lookup.
             env_overrides: Caller-supplied env-var override mapping.
             runtime_label: Label for diagnostic messages.
@@ -1432,18 +1500,38 @@ class MCPClientAdapter(ABC):
                 instantiate.  Passed by the caller so tests can patch the right
                 module-level name.
         """
+        from ...core.auth import AuthResolver
+        from ...models.dependency.mcp import ManifestHeaderValue
+
         server_name = server_info.get("name", "")
         is_github_server = self._is_github_server(server_name, remote.get("url", ""))
         local_token_injected = False
-        if is_github_server:
-            _tm = token_manager_class()
-            github_token = _tm.get_token_for_purpose("copilot") or os.getenv(
-                "GITHUB_PERSONAL_ACCESS_TOKEN"
+        headers = remote.get("headers", []) or []
+        if isinstance(headers, dict):
+            headers = [{"name": name, "value": value} for name, value in headers.items()]
+        explicit_authorization = any(
+            isinstance(header, dict)
+            and isinstance(header.get("name"), str)
+            and header["name"].casefold() == "authorization"
+            and isinstance(header.get("value"), ManifestHeaderValue)
+            and bool(header.get("value"))
+            for header in headers
+        )
+        if is_github_server and not explicit_authorization:
+            resolver = AuthResolver(
+                token_manager=token_manager_class(), allow_external_fallback=False
             )
-            if github_token:
-                config["headers"] = {"Authorization": f"Bearer {github_token}"}
+            selected = resolver.resolve_github_mcp_token(
+                source_only=self._supports_runtime_env_substitution
+            )
+            if selected:
+                credential = (
+                    self._format_runtime_env_placeholder(selected)
+                    if self._supports_runtime_env_substitution
+                    else selected
+                )
+                config.setdefault("headers", {})["Authorization"] = f"Bearer {credential}"
                 local_token_injected = True
-        headers = remote.get("headers", [])
         if headers:
             if "headers" not in config:
                 config["headers"] = {}
@@ -1451,8 +1539,15 @@ class MCPClientAdapter(ABC):
                 header_name = header.get("name", "")
                 header_value = header.get("value", "")
                 if header_name and header_value:
-                    if header_name == "Authorization" and local_token_injected:
-                        continue
+                    if header_name.casefold() == "authorization":
+                        if local_token_injected or (
+                            explicit_authorization
+                            and not isinstance(header_value, ManifestHeaderValue)
+                        ):
+                            continue
+                        for key in list(config["headers"]):
+                            if key.casefold() == "authorization":
+                                del config["headers"][key]
                     resolved_value = self._resolve_env_variable(
                         header_name, header_value, env_overrides
                     )

{apm_cli-0.32.0 → apm_cli-0.34.0}/src/apm_cli/adapters/client/claude.py

@@ -63,6 +63,14 @@ class ClaudeClientAdapter(CopilotClientAdapter):
     _CONVERGED_SKILL_PREFIX = ".agents/skills/"
     _CLAUDE_SKILL_PREFIX = ".claude/skills/"
 
+    # Entry ``type`` values Claude Code uses for URL-addressed servers.
+    _REMOTE_TYPES = ("http", "sse", "streamable-http")
+
+    # Transport fields are replaced across families; a partial update can
+    # retain an omitted type only when it still belongs to the selected family.
+    _REMOTE_TRANSPORT_KEYS = frozenset({"type", "url", "headers"})
+    _STDIO_TRANSPORT_KEYS = frozenset({"type", "command", "args", "env", "cwd"})
+
     @classmethod
     def _rewrite_self_defined_skill_command(cls, command: str) -> str:
         if isinstance(command, str) and command.startswith(cls._CONVERGED_SKILL_PREFIX):
@@ -75,8 +83,13 @@ class ClaudeClientAdapter(CopilotClientAdapter):
             config["command"] = self._rewrite_self_defined_skill_command(config["command"])
         return config
 
-    @staticmethod
-    def _normalize_mcp_entry_for_claude_code(entry: dict) -> dict:
+    @classmethod
+    def _is_remote_mcp_entry(cls, entry: dict) -> bool:
+        """Return whether *entry* describes a remote (URL-addressed) server."""
+        return bool(entry.get("url")) or entry.get("type") in cls._REMOTE_TYPES
+
+    @classmethod
+    def _normalize_mcp_entry_for_claude_code(cls, entry: dict) -> dict:
         """Normalize a server entry to Claude Code's on-disk shape.
 
         For remote servers, keep ``type``/``url``/``headers`` per Claude
@@ -91,11 +104,8 @@ class ClaudeClientAdapter(CopilotClientAdapter):
         if not isinstance(entry, dict):
             return entry
         out = dict(entry)
-        url = out.get("url")
-        t = out.get("type")
-        is_remote = bool(url) or t in ("http", "sse", "streamable-http")
 
-        if is_remote:
+        if cls._is_remote_mcp_entry(out):
             if out.get("id") in ("", None):
                 out.pop("id", None)
             if out.get("tools") == ["*"]:
@@ -110,14 +120,43 @@ class ClaudeClientAdapter(CopilotClientAdapter):
             out.pop("id", None)
         return out
 
-    @staticmethod
-    def _merge_mcp_server_dicts(existing_servers: dict, config_updates: dict) -> None:
+    @classmethod
+    def _retained_previous_entry(cls, prev: dict, new_cfg: dict) -> dict:
+        """Return *prev* without the keys of the transport *new_cfg* is not.
+
+        A redeclaration that switches transport must not leave the previous
+        transport's keys behind.  A surviving ``url`` keeps the entry
+        classified as remote, so the stdio shape never wins and a stale
+        ``Authorization`` header stays in the Claude Code config.
+
+        The keys are selected from the update rather than from a comparison
+        of the two entries, so an entry already carrying both transports --
+        written by a release that merged them unconditionally -- is repaired
+        by the next install that writes it instead of matching its own mixed shape and
+        surviving.  Keys APM does not manage (hand-authored OAuth blocks and
+        the like) describe no transport and are retained either way.
+        """
+        declares_transport = any(new_cfg.get(key) for key in ("type", "url", "command"))
+        is_remote = cls._is_remote_mcp_entry(new_cfg if declares_transport else prev)
+        stale = cls._STDIO_TRANSPORT_KEYS if is_remote else cls._REMOTE_TRANSPORT_KEYS
+        compatible_types = cls._REMOTE_TYPES if is_remote else ("local", "stdio")
+        # Keep a compatible type in place so repeated writes retain field order.
+        return {
+            key: value
+            for key, value in prev.items()
+            if key not in stale or (key == "type" and value in compatible_types)
+        }
+
+    @classmethod
+    def _merge_mcp_server_dicts(cls, existing_servers: dict, config_updates: dict) -> None:
         """Merge *config_updates* into *existing_servers* in place.
 
         Per-server entries are shallow-merged: ``{**old, **new}`` so keys present
-        only on plugin- or hand-authored configs (e.g. ``type``, OAuth blocks)
+        only on plugin- or hand-authored configs (e.g. OAuth blocks)
         survive when an update omits them.  Keys in *new* overwrite *old* on
         conflict so APM/registry installs still refresh ``command``/``args``/etc.
+        The previous entry first drops the keys of the transport the update
+        does not declare, so the merged entry describes exactly one.
         """
         for name, new_cfg in config_updates.items():
             if not isinstance(new_cfg, dict):
@@ -125,7 +164,7 @@ class ClaudeClientAdapter(CopilotClientAdapter):
                 continue
             prev = existing_servers.get(name)
             if isinstance(prev, dict):
-                merged = {**prev, **new_cfg}
+                merged = {**cls._retained_previous_entry(prev, new_cfg), **new_cfg}
                 existing_servers[name] = merged
             else:
                 existing_servers[name] = dict(new_cfg)
@@ -145,7 +184,12 @@ class ClaudeClientAdapter(CopilotClientAdapter):
     def _project_mcp_path(self) -> Path:
         return self.project_root / ".mcp.json"
 
-    def _user_claude_json_path(self) -> Path:
+    @classmethod
+    def resolve_user_claude_unresolved_path(cls) -> Path:
+        """Return the un-normalized path for user-scope Claude Code config.
+
+        Used for symlink pre-checks before canonical resolution.
+        """
         config_dir = os.environ.get("CLAUDE_CONFIG_DIR", "").strip()
         if config_dir:
             config_path = Path(config_dir).expanduser()
@@ -154,9 +198,22 @@ class ClaudeClientAdapter(CopilotClientAdapter):
                     "CLAUDE_CONFIG_DIR must be an absolute path for user-scope MCP "
                     "config; set an absolute path or unset it to use ~/.claude.json."
                 )
-            return config_path.resolve(strict=False) / ".claude.json"
+            return config_path / ".claude.json"
         return Path.home() / ".claude.json"
 
+    @classmethod
+    def resolve_user_claude_json_path(cls, unresolved_path: Path | None = None) -> Path:
+        """Resolve the selected destination, optionally reusing a checked path."""
+        path = (
+            unresolved_path
+            if unresolved_path is not None
+            else cls.resolve_user_claude_unresolved_path()
+        )
+        return path.parent.resolve(strict=False) / path.name
+
+    def _user_claude_json_path(self) -> Path:
+        return self.resolve_user_claude_json_path()
+
     def _should_write_project(self) -> bool:
         return (self.project_root / ".claude").is_dir()
 

{apm_cli-0.32.0 → apm_cli-0.34.0}/src/apm_cli/adapters/client/codex.py

@@ -2,6 +2,7 @@
 
 import logging
 import os
+import re
 from pathlib import Path
 from urllib.parse import urlparse
 
@@ -15,10 +16,34 @@ from ...utils.console import _rich_success, _rich_warning
 from ...utils.net import is_loopback_host
 from ...utils.path_security import PathTraversalError
 from ._mcp_runtime_args import process_v01_value_hint_arg
-from .base import MCPClientAdapter
+from .base import _ENV_VAR_RE, MCPClientAdapter
 
 _log = logging.getLogger(__name__)
 
+# Codex documents ``http_headers`` as a map of header names to STATIC values,
+# so a ``${VAR}`` written there reaches the server as that literal text. An
+# environment-sourced header has two dedicated fields instead:
+# ``env_http_headers`` maps a header name to the variable holding its whole
+# value, and ``bearer_token_env_var`` names the variable holding an
+# Authorization bearer token. Codex resolves both at server start, which is
+# what the declared ``${VAR}`` asks for -- this adapter does not support
+# runtime substitution itself, so the placeholder survives
+# ``_resolve_variable_placeholders`` untouched.
+# See https://learn.chatgpt.com/docs/extend/mcp?surface=cli
+_CODEX_BEARER_HEADER = "authorization"
+# Reuse the canonical placeholder syntax so the two spellings APM accepts
+# (``${VAR}`` and ``${env:VAR}``) cannot drift apart here. The auth scheme is
+# case-insensitive per RFC 7235; Codex always writes it as ``Bearer``.
+_CODEX_BEARER_VALUE_RE = re.compile(rf"(?i:Bearer) +{_ENV_VAR_RE.pattern}")
+# Any reference still standing in a resolved value, deliberately wider than the
+# canonical parser: a spelling it does not model, such as the shell default in
+# ``${VAR:-}``, is no more static than a ``${VAR}`` Codex could resolve, and
+# writing it to ``http_headers`` sends the braces to the server. Widening the
+# report here, rather than the parser, keeps every other adapter's placeholder
+# semantics untouched. ``${input:...}`` is excluded: input variables are
+# collected elsewhere and carry their own warning.
+_CODEX_UNSUPPORTED_REFERENCE_RE = re.compile(r"\$\{(?!input:)")
+
 
 class CodexClientAdapter(MCPClientAdapter):
     """Codex CLI implementation of MCP client adapter.
@@ -293,16 +318,49 @@ class CodexClientAdapter(MCPClientAdapter):
                 "id": server_info.get("id", ""),
             }
             http_headers: dict[str, str] = {}
+            env_http_headers: dict[str, str] = {}
+            bearer_token_env_var = ""
+            unsupported_headers: list[str] = []
             for header in remote.get("headers", []):
                 h_name = header.get("name", "")
                 h_value = header.get("value", "")
-                if h_name and h_value:
-                    http_headers[h_name] = self._resolve_variable_placeholders(
-                        h_value, env_overrides or {}, runtime_vars or {}
-                    )
+                if not (h_name and h_value):
+                    continue
+                resolved = self._resolve_variable_placeholders(
+                    h_value, env_overrides or {}, runtime_vars or {}
+                )
+                bearer = _CODEX_BEARER_VALUE_RE.fullmatch(resolved)
+                if bearer and h_name.lower() == _CODEX_BEARER_HEADER:
+                    bearer_token_env_var = bearer.group(1)
+                    continue
+                env_header = _ENV_VAR_RE.fullmatch(resolved)
+                if env_header:
+                    env_http_headers[h_name] = env_header.group(1)
+                    continue
+                if _CODEX_UNSUPPORTED_REFERENCE_RE.search(resolved):
+                    unsupported_headers.append(h_name)
+                    continue
+                http_headers[h_name] = resolved
+            if unsupported_headers:
+                safe_headers = ", ".join(ascii(name)[1:-1] for name in unsupported_headers)
+                safe_server = ascii(server_name)[1:-1]
+                _rich_warning(
+                    f"Skipping header(s) {safe_headers} of MCP server "
+                    f"'{safe_server}' for Codex CLI: Codex reads a header from the "
+                    "environment only when the value is exactly ${VAR} or, for "
+                    "Authorization, `Bearer ${VAR}`. Literal text around the "
+                    "reference, or a shell-style default such as ${VAR:-}, has no "
+                    "Codex equivalent; export the whole header value as one variable.",
+                    symbol="warning",
+                )
+            # Scalars precede the sub-tables tomlkit renders for the dict values.
+            if bearer_token_env_var:
+                remote_config["bearer_token_env_var"] = bearer_token_env_var
             if http_headers:
                 remote_config["http_headers"] = http_headers
                 self._warn_input_variables(http_headers, server_name, "Codex CLI")
+            if env_http_headers:
+                remote_config["env_http_headers"] = env_http_headers
             self._merge_extra(remote_config, server_info)
             return remote_config
 

{apm_cli-0.32.0 → apm_cli-0.34.0}/src/apm_cli/adapters/client/copilot.py

@@ -55,11 +55,12 @@ class CopilotClientAdapter(MCPClientAdapter):
     # environment and the literal value is baked into the config file
     # (legacy pre-#1152 behaviour).
     #
-    # Subclasses (Cursor / Windsurf / OpenCode / Claude / Gemini) override
-    # this to ``False`` until their respective config formats are individually
-    # audited for runtime-substitution support. Critically, Claude Desktop's
-    # config format does NOT support runtime substitution -- it MUST keep
-    # resolving at install time.
+    # Subclasses (Windsurf / OpenCode / Claude / Gemini) override this to
+    # ``False`` until their respective config formats are individually audited
+    # for runtime-substitution support. Cursor has audited native
+    # ``${env:VAR}`` support. Critically, Claude Desktop's config format does
+    # NOT support runtime substitution -- it MUST keep resolving at install
+    # time.
     _supports_runtime_env_substitution: bool = True
 
     # Process-wide aggregation of legacy ``<VAR>`` offenders, keyed by