apm-cli 0.14.1__tar.gz → 0.14.2__tar.gz

{apm_cli-0.14.1 → apm_cli-0.14.2}/NOTICE

@@ -1252,6 +1252,46 @@ SOFTWARE.
 
 ---
 
+## Component. websockets
+
+- Version requirement: `>=12,<17`
+- Upstream: https://github.com/python-websockets/websockets
+- SPDX: `BSD-3-Clause`
+- Notes: Used by the copilot-app integrator to nudge the Copilot desktop App over its local WebSocket IPC channel after writing workflows to the App DB.
+
+### Open Source License/Copyright Notice.
+
+_Copyright (c) Aymeric Augustin and contributors_
+
+```
+Copyright (c) Aymeric Augustin and contributors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice,
+      this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright notice,
+      this list of conditions and the following disclaimer in the documentation
+      and/or other materials provided with the distribution.
+    * Neither the name of the copyright holder nor the names of its contributors
+      may be used to endorse or promote products derived from this software
+      without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+```
+
+---
+
 Submitted on behalf of a third-party
 
 The contributions below are identified as submitted on behalf of a

{apm_cli-0.14.1/src/apm_cli.egg-info → apm_cli-0.14.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: apm-cli
-Version: 0.14.1
+Version: 0.14.2
 Summary: MCP configuration tool
 Author-email: Daniel Meppiel <user@example.com>
 License: MIT License
@@ -52,6 +52,7 @@ Requires-Dist: watchdog>=3.0.0
 Requires-Dist: GitPython>=3.1.0
 Requires-Dist: ruamel.yaml>=0.18.0
 Requires-Dist: filelock>=3.12
+Requires-Dist: websockets<17,>=12
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
@@ -219,8 +220,6 @@ 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
 ```
 
-> *Codex CLI currently does not support remote MCP servers; the install will skip Codex with a notice. Omit `--transport http` to use the local Docker variant on Codex (requires `GITHUB_PERSONAL_ACCESS_TOKEN`).*
-
 See the **[Getting Started guide](https://microsoft.github.io/apm/getting-started/quick-start/)** for the full walkthrough.
 
 ## Works with agentrc

{apm_cli-0.14.1 → apm_cli-0.14.2}/README.md

@@ -152,8 +152,6 @@ 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
 ```
 
-> *Codex CLI currently does not support remote MCP servers; the install will skip Codex with a notice. Omit `--transport http` to use the local Docker variant on Codex (requires `GITHUB_PERSONAL_ACCESS_TOKEN`).*
-
 See the **[Getting Started guide](https://microsoft.github.io/apm/getting-started/quick-start/)** for the full walkthrough.
 
 ## Works with agentrc

{apm_cli-0.14.1 → apm_cli-0.14.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "apm-cli"
-version = "0.14.1"
+version = "0.14.2"
 description = "MCP configuration tool"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -37,6 +37,7 @@ dependencies = [
     "GitPython>=3.1.0",
     "ruamel.yaml>=0.18.0",
     "filelock>=3.12",
+    "websockets>=12,<17",
 ]
 
 [project.optional-dependencies]
@@ -137,6 +138,7 @@ parallel = true
 [tool.coverage.report]
 show_missing = true
 skip_empty = true
+fail_under = 80
 # Exclude lines that are not meant to be covered
 exclude_lines = [
     "pragma: no cover",

{apm_cli-0.14.1 → apm_cli-0.14.2}/src/apm_cli/adapters/client/base.py

@@ -4,6 +4,7 @@ import os
 import re
 from abc import ABC, abstractmethod
 from pathlib import Path
+from typing import ClassVar
 
 from ...utils.console import _rich_error, _rich_warning
 
@@ -16,6 +17,80 @@ _INPUT_VAR_RE = re.compile(r"\$\{input:([^}]+)\}")
 # variable handling, so existing _INPUT_VAR_RE call sites are unaffected.
 _ENV_VAR_RE = re.compile(r"\$\{(?:env:)?([A-Za-z_][A-Za-z0-9_]*)\}")
 
+# Superset of _ENV_VAR_RE that also matches the legacy ``<VAR>`` syntax
+# (uppercase identifier only). Used as the single-pass translation target so
+# resolved values are NOT re-scanned -- a literal value whose text happens to
+# contain ``${...}`` does not get recursively expanded. ``${input:...}`` is
+# intentionally not matched here so input-variable handling stays disjoint.
+_ENV_PLACEHOLDER_RE = re.compile(r"<([A-Z_][A-Z0-9_]*)>|" + _ENV_VAR_RE.pattern)
+
+# Detects the legacy ``<VAR>`` placeholder syntax only. Used to aggregate
+# deprecation warnings across all servers in a single install run.
+_LEGACY_ANGLE_VAR_RE = re.compile(r"<([A-Z_][A-Z0-9_]*)>")
+
+
+def _translate_env_placeholder(value):
+    """Pure-textual translation of env-var placeholders to the canonical
+    ``${VAR}`` runtime-substitution syntax.
+
+    Security-critical helper for issue #1152: MUST NOT read ``os.environ``
+    and MUST NOT resolve placeholders to literal values. Runtimes that
+    support runtime substitution (Copilot CLI) resolve ``${VAR}`` from the
+    host environment at server-start, so APM emits placeholders verbatim
+    rather than baking secrets to disk.
+
+    Translations:
+        ``${env:VAR}``     -> ``${VAR}``     (strip ``env:`` prefix)
+        ``${VAR}``         -> ``${VAR}``     (no-op)
+        ``<VAR>``          -> ``${VAR}``     (legacy syntax migration)
+        ``${VAR:-default}``-> passthrough    (regex doesn't match)
+        ``$VAR`` (bare)    -> passthrough    (regex doesn't match)
+        ``${input:foo}``   -> passthrough    (regex doesn't match)
+        non-string         -> passthrough
+
+    Idempotent: applying twice yields the same result as applying once.
+    """
+    if not isinstance(value, str):
+        return value
+
+    def _to_brace(match):
+        # group(1) = legacy <VAR>; group(2) = ${VAR} / ${env:VAR}
+        var_name = match.group(1) or match.group(2)
+        return "${" + var_name + "}"
+
+    return _ENV_PLACEHOLDER_RE.sub(_to_brace, value)
+
+
+def _extract_legacy_angle_vars(value):
+    """Return the set of legacy ``<VAR>`` names present in *value*.
+
+    Used to aggregate deprecation warnings across all servers in a single
+    install run, so authors see one helpful list instead of one warning per
+    occurrence.
+    """
+    if not isinstance(value, str):
+        return set()
+    return set(_LEGACY_ANGLE_VAR_RE.findall(value))
+
+
+def _has_env_placeholder(value):
+    """True if *value* is a string containing any recognised env-var
+    placeholder syntax (``${VAR}``, ``${env:VAR}``, or legacy ``<VAR>``).
+
+    Used to distinguish placeholder-sourced env values (which translate)
+    from hardcoded literal defaults (which stay literal).
+    """
+    if not isinstance(value, str):
+        return False
+    return bool(_ENV_PLACEHOLDER_RE.search(value))
+
+
+def _stringify_env_literal(value):
+    """Return MCP env literal values in the manifest ``map<string, string>`` shape."""
+    if isinstance(value, bool):
+        return str(value).lower()
+    return str(value)
+
 
 class MCPClientAdapter(ABC):
     """Base adapter for MCP clients."""
@@ -44,6 +119,13 @@ class MCPClientAdapter(ABC):
     # so that ``apm install --global`` can install MCP servers to them.
     supports_user_scope: bool = False
 
+    # Whether the target runtime resolves ``${VAR}`` placeholders from the
+    # host environment at server-start time. Adapters that opt in (Copilot
+    # CLI) emit placeholders verbatim so secrets never touch disk; legacy
+    # adapters resolve to literal values at install time via env_overrides
+    # -> os.environ -> optional interactive prompt. See issue #1152.
+    _supports_runtime_env_substitution: bool = False
+
     def __init__(
         self,
         project_root: Path | str | None = None,
@@ -60,6 +142,13 @@ class MCPClientAdapter(ABC):
         """
         self._project_root = Path(project_root) if project_root is not None else None
         self.user_scope = user_scope
+        # Per-server tracking populated by the env-resolution helpers and
+        # consumed by ``configure_mcp_server`` for the post-install summary
+        # and the aggregated legacy-syntax deprecation warning. Defined on
+        # the base so every adapter has the attributes regardless of which
+        # subclass path constructed it.
+        self._last_env_placeholder_keys: set[str] = set()
+        self._last_legacy_angle_vars: set[str] = set()
 
     @property
     def project_root(self) -> Path:
@@ -159,6 +248,46 @@ class MCPClientAdapter(ABC):
 
         return ""
 
+    @classmethod
+    def _select_best_package(cls, packages):
+        """Select the best package for installation from available packages.
+
+        Prioritizes packages in order: npm, docker, pypi, homebrew, others.
+        Uses ``_infer_registry_name`` so selection works even when the
+        registry API returns empty ``registry_name``.
+
+        Args:
+            packages (list): List of package dictionaries.
+
+        Returns:
+            dict: Best package to use, or None if no suitable package found.
+        """
+        priority_order = ["npm", "docker", "pypi", "homebrew"]
+
+        for target in priority_order:
+            for package in packages:
+                if cls._infer_registry_name(package) == target:
+                    return package
+
+        # If no priority package found, return the first one
+        return packages[0] if packages else None
+
+    @staticmethod
+    def _select_remote_with_url(remotes):
+        """Return the first remote entry that has a non-empty URL.
+
+        Args:
+            remotes (list): Candidate remote entries from the registry.
+
+        Returns:
+            dict or None: The first usable remote, or None if none qualify.
+        """
+        for remote in remotes:
+            url = (remote.get("url") or "").strip()
+            if url:
+                return remote
+        return None
+
     @staticmethod
     def _warn_input_variables(mapping, server_name, runtime_label):
         """Emit a warning for each ``${input:...}`` reference found in *mapping*.
@@ -199,6 +328,270 @@ class MCPClientAdapter(ABC):
             return "."
         return value
 
+    # -- Env-var placeholder resolution -------------------------------------
+    # GitHub MCP server defaults: not secrets, preserved literal in translate
+    # mode and used as fallbacks in legacy mode. The defaults apply regardless
+    # of which client CLI runs the server, so they live on the base.
+    _DEFAULT_GITHUB_ENV: ClassVar[dict[str, str]] = {
+        "GITHUB_TOOLSETS": "context",
+        "GITHUB_DYNAMIC_TOOLSETS": "1",
+    }
+
+    @staticmethod
+    def _should_skip_env_prompts(env_overrides):
+        """True when the caller has already collected env vars (managed mode),
+        when APM_E2E_TESTS is set, or when stdin/stdout is not a TTY.
+
+        Centralising this policy keeps the resolver paths consistent and
+        avoids subtle drift between ``_resolve_environment_variables`` and
+        ``_resolve_env_variable``.
+        """
+        import sys
+
+        if env_overrides:
+            return True
+        if os.getenv("APM_E2E_TESTS") == "1":
+            return True
+        return not (sys.stdin.isatty() and sys.stdout.isatty())
+
+    def _resolve_environment_variables(self, env_vars, env_overrides=None):
+        """Resolve (or translate) declared environment variables.
+
+        Behaviour follows ``self._supports_runtime_env_substitution``:
+        translate-mode (Copilot CLI) emits ``${VAR}`` placeholders verbatim
+        so the runtime resolves them at server-start (see issue #1152);
+        legacy-mode resolves placeholders to literal values via env_overrides
+        -> os.environ -> optional interactive prompt.
+
+        Args:
+            env_vars: Either a ``dict[name, value-or-placeholder]`` from a
+                self-defined stdio dep (``_raw_stdio["env"]``), or a
+                ``list[{name, description, required}]`` from the registry.
+            env_overrides: Pre-collected env-var overrides (ignored in
+                translate mode).
+
+        Returns:
+            dict: ``{name: value}`` -- placeholder string in translate
+            mode, literal value in legacy mode.
+        """
+        # ---- translate mode, dict shape (self-defined stdio in apm.yml) ----
+        if isinstance(env_vars, dict) and self._supports_runtime_env_substitution:
+            # Value type is intentionally untyped: most entries are translated
+            # placeholder strings, but non-string values (e.g. an int/bool
+            # YAML scalar) are passed through verbatim and serialised by the
+            # adapter's config writer (JSON/TOML).
+            translated: dict = {}
+            placeholder_keys: list[str] = []
+            for name, raw_value in env_vars.items():
+                if not name:
+                    continue
+                if not isinstance(raw_value, str):
+                    translated[name] = raw_value
+                    continue
+                if _has_env_placeholder(raw_value):
+                    self._last_legacy_angle_vars.update(_extract_legacy_angle_vars(raw_value))
+                    translated[name] = _translate_env_placeholder(raw_value)
+                    # Record every ${VAR} in the translated value (handles
+                    # both ${env:VAR} -> ${VAR} and bare ${VAR} cases).
+                    placeholder_keys.extend(
+                        m.group(1) for m in _ENV_VAR_RE.finditer(translated[name])
+                    )
+                elif (
+                    name in self._DEFAULT_GITHUB_ENV and raw_value == self._DEFAULT_GITHUB_ENV[name]
+                ):
+                    translated[name] = raw_value
+                else:
+                    # Literal value present in apm.yml -- replace with a
+                    # runtime placeholder so the secret never touches disk.
+                    translated[name] = "${" + name + "}"
+                    placeholder_keys.append(name)
+            self._last_env_placeholder_keys = set(placeholder_keys)
+            return translated
+
+        # ---- translate mode, registry list shape ----
+        if self._supports_runtime_env_substitution:
+            resolved: dict[str, str] = {}
+            placeholder_keys: list[str] = []
+            for env_var in env_vars:
+                if not isinstance(env_var, dict):
+                    continue
+                name = env_var.get("name", "")
+                if not name:
+                    continue
+                if name in self._DEFAULT_GITHUB_ENV:
+                    resolved[name] = self._DEFAULT_GITHUB_ENV[name]
+                else:
+                    resolved[name] = "${" + name + "}"
+                    placeholder_keys.append(name)
+            self._last_env_placeholder_keys = set(placeholder_keys)
+            return resolved
+
+        # ---- legacy mode, dict shape (self-defined stdio in apm.yml) ----
+        # Issue #1266 / #1222: ``_raw_stdio["env"]`` is a plain dict. Each
+        # value is resolved via the same single-value pipeline used for
+        # header values so all three placeholder syntaxes (``<VAR>``,
+        # ``${VAR}``, ``${env:VAR}``) behave consistently across adapters.
+        #
+        # Note the deliberate semantic divergence from the legacy-list branch
+        # below: empty strings authored in apm.yml are preserved as-is and
+        # ``_DEFAULT_GITHUB_ENV`` fallbacks are NOT applied, because a value
+        # explicitly written by the user expresses intent, whereas an empty
+        # value coming from ``env_overrides`` / ``os.environ`` for a
+        # registry-declared schema entry means "no value supplied, use the
+        # default if one exists".
+        if isinstance(env_vars, dict):
+            resolved = {}
+            for name, value in env_vars.items():
+                if not name:
+                    continue
+                if isinstance(value, str):
+                    resolved[name] = self._resolve_env_variable(
+                        name, value, env_overrides=env_overrides
+                    )
+                elif value is not None:
+                    resolved[name] = str(value)
+            return resolved
+
+        # ---- legacy mode, registry list shape ----
+        from rich.prompt import Prompt
+
+        env_overrides = env_overrides or {}
+        skip_prompting = self._should_skip_env_prompts(env_overrides)
+
+        # Variables explicitly provided with empty values mean "use the default".
+        empty_value_vars = {k for k, v in env_overrides.items() if not v or not v.strip()}
+
+        resolved = {}
+        for env_var in env_vars:
+            if not isinstance(env_var, dict):
+                continue
+            name = env_var.get("name", "")
+            if not name:
+                continue
+            required = env_var.get("required", True)
+
+            value = env_overrides.get(name) or os.getenv(name)
+            if not value and required and not skip_prompting:
+                prompt_text = f"Enter value for {name}"
+                if description := env_var.get("description", ""):
+                    prompt_text += f" ({description})"
+                value = Prompt.ask(
+                    prompt_text,
+                    password="token" in name.lower() or "key" in name.lower(),
+                )
+
+            if value and value.strip():
+                resolved[name] = value
+            elif name in self._DEFAULT_GITHUB_ENV and (
+                name in empty_value_vars or not required or skip_prompting
+            ):
+                resolved[name] = self._DEFAULT_GITHUB_ENV[name]
+
+        return resolved
+
+    def _resolve_env_variable(self, name, value, env_overrides=None):
+        """Resolve (or translate) a single env-var value.
+
+        Used for header values and for individual entries in dict-shape
+        env blocks. The ``name`` parameter is currently unused by the
+        method body but kept in the signature because every call site
+        (headers, dict iteration) already has the name in hand, and
+        passing it preserves call-site symmetry with future hooks that
+        may want to dispatch on it.
+
+        Args:
+            name: Env-var name (currently unused, see above).
+            value: Env-var value possibly containing placeholders.
+            env_overrides: Pre-collected overrides (ignored in translate mode).
+        """
+        if self._supports_runtime_env_substitution:
+            legacy_keys = _extract_legacy_angle_vars(value)
+            self._last_legacy_angle_vars.update(legacy_keys)
+            self._last_env_placeholder_keys.update(legacy_keys)
+            for match in _ENV_VAR_RE.finditer(value):
+                self._last_env_placeholder_keys.add(match.group(1))
+            return _translate_env_placeholder(value)
+
+        from rich.prompt import Prompt
+
+        env_overrides = env_overrides or {}
+        skip_prompting = self._should_skip_env_prompts(env_overrides)
+
+        # Three accepted placeholder syntaxes resolved against
+        # env_overrides -> os.environ -> optional interactive prompt.
+        # Single-pass substitution preserves the legacy ``<VAR>`` semantics:
+        # resolved values are NOT re-scanned for further expansion.
+        def _replace(match):
+            env_name = match.group(1) or match.group(2)
+            env_value = env_overrides.get(env_name) or os.getenv(env_name)
+            if not env_value and not skip_prompting:
+                env_value = Prompt.ask(
+                    f"Enter value for {env_name}",
+                    password="token" in env_name.lower() or "key" in env_name.lower(),
+                )
+            return env_value if env_value else match.group(0)
+
+        return _ENV_PLACEHOLDER_RE.sub(_replace, value)
+
+    def _resolve_variable_placeholders(self, value, resolved_env, runtime_vars):
+        """Resolve env-var and APM template placeholders in argument strings.
+
+        Translate mode rewrites all three env-var placeholder syntaxes to
+        ``${VAR}`` (so the runtime can resolve them at server-start); legacy
+        mode resolves only the legacy ``<VAR>`` form against ``resolved_env``
+        and leaves the newer ``${VAR}`` / ``${env:VAR}`` syntaxes untouched
+        for backward compatibility. APM template variables (``{runtime_var}``)
+        are always resolved at install time because they are an APM-internal
+        concept the target runtime cannot interpret.
+
+        Args:
+            value: String possibly containing placeholders.
+            resolved_env: Resolved env-var literals (legacy mode) or
+                placeholder strings (translate mode).
+            runtime_vars: Resolved APM template variables.
+
+        Returns:
+            str: ``value`` with placeholders translated or resolved.
+        """
+        if not value:
+            return value
+
+        processed = str(value)
+
+        if self._supports_runtime_env_substitution:
+            self._last_legacy_angle_vars.update(_extract_legacy_angle_vars(processed))
+            processed = _translate_env_placeholder(processed)
+        else:
+            # Resolve only the legacy ``<VAR>`` form; newer syntaxes are
+            # preserved verbatim for backward compatibility.
+            def _replace_legacy_angle(match):
+                return resolved_env.get(match.group(1), match.group(0))
+
+            processed = _LEGACY_ANGLE_VAR_RE.sub(_replace_legacy_angle, processed)
+
+        # Resolve APM ``{runtime_var}`` template variables. The negative
+        # lookbehind on ``$`` ensures we never accidentally match the brace
+        # of an already-translated ``${VAR}`` env placeholder.
+        if runtime_vars:
+            runtime_pattern = re.compile(r"(?<!\$)\{([a-zA-Z_][a-zA-Z0-9_]*)\}")
+
+            def _replace_runtime(match):
+                return runtime_vars.get(match.group(1), match.group(0))
+
+            processed = runtime_pattern.sub(_replace_runtime, processed)
+
+        return processed
+
+    def _resolve_env_placeholders(self, value, resolved_env):
+        """Legacy thin wrapper for backward compatibility.
+
+        Kept because external callers and the phase-3 test suite invoke
+        the pre-#1277 name. Delegates to ``_resolve_variable_placeholders``
+        with an empty ``runtime_vars`` map. New code should call
+        ``_resolve_variable_placeholders`` directly.
+        """
+        return self._resolve_variable_placeholders(value, resolved_env, {})
+
     # ------------------------------------------------------------------
     # Shared server-info helpers (used by all adapter subclasses)
     # ------------------------------------------------------------------
@@ -401,10 +794,19 @@ class MCPClientAdapter(ABC):
             if not name:
                 continue
 
-            # Priority 1: caller-supplied override
+            # Priority 1: caller-supplied override.
+            # An explicit empty (or whitespace-only) value is treated as
+            # "user cleared this". For names with a GitHub-style default the
+            # logic falls through so the literal default wins; for names
+            # without a default the entry is dropped from the resolved map.
             if name in env_overrides:
-                resolved[name] = env_overrides[name]
-                continue
+                override_value = env_overrides[name]
+                if isinstance(override_value, str) and not override_value.strip():
+                    if name not in default_github_env:
+                        continue
+                else:
+                    resolved[name] = override_value
+                    continue
 
             # Priority 2: check GitHub-specific defaults (values are literal defaults, not env-var names)
             if name in default_github_env: