fix: hint to host-qualify cross-repo on *.ghe.com (closes microsoft#1305)

PR microsoft#1292 fixed the silent ``github.com`` auth fallback for **in-marketplace**
plugin sources on ``*.ghe.com`` marketplaces but deliberately scoped its host
backfill via ``_is_in_marketplace_source`` to avoid changing routing for
cross-repo dict sources. A bare cross-repo ``repo: owner/proj`` on an enterprise
marketplace still legitimately means two different things -- a real
``github.com`` open-source dep, or a misconfigured same-host entry that should
have been ``corp.ghe.com/owner/proj`` -- and the resolver cannot disambiguate
them. The silent mis-route survives for the second intent: the canonical stays
bare, ``DependencyReference.parse`` defaults the host to ``github.com``, and
the install path reports the generic
``not accessible or doesn't exist -- run with --verbose for auth details``
with zero pointer at the marketplace's enterprise host.

Surface the diagnostic at the install-time validation-failure boundary, not
at resolver time. The legitimate cross-host case validates successfully and
never sees a hint; the misconfigured case fails validation and gets an
actionable host-qualified suggestion. The resolver-time always-on warning
the PR microsoft#1292 review panel rejected -- which would false-positive on the
legitimate case and train operators to ignore -- is avoided.

Approach
========

Resolver attaches a typed ``CrossRepoMisconfigRisk`` sentinel to
``MarketplacePluginResolution`` when **all** of:

- ``dependency_reference`` is ``None`` (GitHub-family virtual-shorthand path;
  GitLab-class and self-managed FQDN marketplaces build a structured ref
  upstream and sidestep the bug)
- ``plugin.source`` is a dict whose normalized type is ``github`` -- via the
  existing ``_coerce_dict_plugin_type`` (covers ``type``/``kind``/``source``
  synonyms plus the inferred-github fallback). Cross-repo ``gitlab`` /
  ``git-subdir`` dict sources on enterprise marketplaces hit the same
  auth-routing bug but the "host-qualify with marketplace host" remediation
  only matches operator intent for the GitHub family.
- the source is NOT an in-marketplace reference (PR microsoft#1292's domain)
- ``_needs_canonical_host_prefix`` agrees the canonical is bare and the host
  is GitHub-family enterprise (``*.ghe.com``; idempotent against already
  host-qualified, URL, and SSH forms)
- the ``repo`` field is a non-empty ``owner/repo`` shorthand

The helper is pure -- no logging, no canonical mutation. Resolver behavior is
unchanged; only the resolution object carries one extra optional field.

Install command records the risk in a per-call ``_misconfig_risks`` dict
**before** validation runs. The existing ``_marketplace_provenance`` map only
gets written on validation success and cannot be relied on at the failure
boundary. When ``_validate_package_exists`` returns ``False`` (which is how
the GitHub-family auth failure surfaces -- ``AuthResolver.try_with_fallback``
collapses 401/404/network into a single ``False``, no typed ``AuthenticationError``),
the validation-fail branch emits the hint inline via ``logger.info`` so the
operator can correct ``marketplace.json`` without rerunning under ``--verbose``
to decode the auth trace.

Why this layer, not ``AuthenticationError``
===========================================

The two ``raise AuthenticationError`` sites in the install pipeline are both
gated to non-GitHub hosts (ADO / self-managed): ``pipeline.py`` preflight skips
``is_github_hostname(host)`` early; ``validation.py`` requires the
``is_ado_auth_failure_signal`` stderr pattern. The github.com fallback path
goes through ``try_with_fallback`` which returns ``False`` on failure, and the
caller records ``(canonical, reason)`` into ``invalid_outcomes``. Decorating
``AuthenticationError`` would be a dead-code hook for this bug -- the typed
exception never fires on the github.com path. The validation-fail branch is
the actual choke point.

Scope and tradeoffs
===================

- 404 typo on the cross-repo ``repo`` field and network failures will also
  trigger the hint; the wording leads with the routing fact ("resolved to
  'github.com'") and the suggestion is conditional ("If you meant the
  enterprise host"), so the false-positive remains advisory rather than
  misleading. Distinguishing 401 from 404/network here would require
  threading HTTP status out of ``try_with_fallback`` -- a much broader
  cross-cutting change.
- The silent-success-on-wrong-host case (cross-repo bare where the same
  ``owner/repo`` happens to exist on github.com with different content)
  cannot be detected without changing the routing semantics PR microsoft#1292
  preserved. This is acknowledged out of scope in the issue.

Tests
=====

``TestCrossRepoMisconfigRisk`` (resolver, 14 cases) locks the truth table for
sentinel attach / no-attach across the dict-type synonyms (``type``, ``kind``,
``source``, inferred-github), host-qualified / URL / SSH / no-slash defensive
guards, the gitlab / git-subdir exclusion, and pure ``github.com`` marketplace
non-pollution.

``TestResolvePackageReferencesCrossRepoMisconfigHint`` (install, 4 cases)
locks the hint emission contract: hint fires only when a risk-bearing
marketplace resolution subsequently fails validation; the legitimate
cross-host path that validates successfully emits no hint; in-marketplace
and plain owner/repo failures emit no hint.

Both test suites were toggle-verified -- removing the resolver helper call or
the install-side emission block makes the corresponding positive case fail.

Author: edenfunf

src/apm_cli/commands/install.py

@@ -349,6 +349,13 @@ def _resolve_package_references(
     invalid_outcomes = []  # (package, reason) tuples
     _marketplace_provenance = {}  # canonical -> {discovered_via, marketplace_plugin_name}
     _apm_yml_entries = {}  # canonical -> apm.yml entry (str or dict for HTTP deps)
+    # #1305: canonical -> (marketplace_name, plugin_name, CrossRepoMisconfigRisk)
+    # for cross-repo dict ``type: github`` sources on enterprise marketplaces
+    # whose bare ``repo`` would mis-route auth at ``github.com``. Recorded
+    # before validation runs so the validation-fail branch can emit an
+    # actionable hint -- ``_marketplace_provenance`` is only written on
+    # validation success and cannot be relied on at the failure boundary.
+    _misconfig_risks = {}
     validated_packages = []
     dependencies_changed = False
 
@@ -403,6 +410,13 @@ def warning_handler(msg):
                     }
                     package = canonical_str
                     marketplace_dep_ref = getattr(resolution, "dependency_reference", None)
+                    _risk = getattr(resolution, "cross_repo_misconfig_risk", None)
+                    if _risk is not None:
+                        _misconfig_risks[canonical_str] = (
+                            marketplace_name,
+                            plugin_name,
+                            _risk,
+                        )
                 except Exception as mkt_err:
                     reason = str(mkt_err)
                     invalid_outcomes.append((package, reason))
@@ -521,6 +535,24 @@ def warning_handler(msg):
             invalid_outcomes.append((package, reason))
             if logger:
                 logger.validation_fail(package, reason)
+            # #1305: when a cross-repo dict ``type: github`` source on an
+            # enterprise marketplace fails validation, the failure is most
+            # likely the silent auth mis-route (bare canonical fell back to
+            # ``github.com``). Surface the host-qualify hint inline so the
+            # operator can correct ``marketplace.json`` without rerunning
+            # under ``--verbose`` to decode the auth trace. The legitimate
+            # cross-host case validates successfully and never reaches here.
+            _risk_entry = _misconfig_risks.get(package)
+            if _risk_entry is not None and logger:
+                _mp_name, _plugin_name, _risk = _risk_entry
+                logger.info(
+                    f"Hint: '{_plugin_name}@{_mp_name}' is registered on "
+                    f"'{_risk.marketplace_host}', but the plugin's bare "
+                    f"`repo: {_risk.bare_repo_field}` resolved to "
+                    "'github.com'. If you meant the enterprise host, set "
+                    "the plugin's `repo` field to "
+                    f"'{_risk.suggested_qualified_repo}' in marketplace.json."
+                )
 
     return (
         valid_outcomes,

src/apm_cli/marketplace/resolver.py

@@ -47,6 +47,29 @@
 _SEMVER_RANGE_CHARS = re.compile(r"[~^<>=!]")
 
 
+@dataclass(frozen=True)
+class CrossRepoMisconfigRisk:
+    """Signal that a cross-repo dict ``type: github`` source on an enterprise
+    GitHub-family marketplace resolved to a bare canonical (#1305).
+
+    Attached to :class:`MarketplacePluginResolution` when the marketplace is on
+    ``*.ghe.com`` and the plugin's dict source declares a bare ``owner/repo``
+    that does not match the marketplace project. The resolver deliberately
+    leaves these canonicals bare (PR #1292 scoped its host backfill to
+    in-marketplace sources), so ``DependencyReference.parse`` defaults the host
+    to ``github.com``. Two intents share this syntax -- a legitimate cross-host
+    ``github.com`` open-source dep, or a misconfigured same-host entry that
+    should have been ``corp.ghe.com/owner/repo`` -- and the resolver cannot
+    distinguish them. The install command consults this sentinel when the
+    package fails validation so an actionable hint surfaces only at the
+    failure boundary, never on the legitimate path.
+    """
+
+    marketplace_host: str
+    bare_repo_field: str
+    suggested_qualified_repo: str
+
+
 @dataclass
 class MarketplacePluginResolution:
     """Outcome of :func:`resolve_marketplace_plugin`.
@@ -57,11 +80,15 @@ class MarketplacePluginResolution:
     subdirectory plugins), install logic should prefer it over
     :meth:`~apm_cli.models.dependency.reference.DependencyReference.parse`
     on :attr:`canonical` to avoid mis-parsing nested paths as GitLab project segments.
+    :attr:`cross_repo_misconfig_risk` is non-``None`` only for the #1305
+    cross-repo bare-on-enterprise pattern; consumers emit it as a hint when the
+    package subsequently fails validation.
     """
 
     canonical: str
     plugin: MarketplacePlugin
     dependency_reference: DependencyReference | None = None
+    cross_repo_misconfig_risk: CrossRepoMisconfigRisk | None = None
 
     def __iter__(self) -> Iterator[str | MarketplacePlugin]:
         yield self.canonical
@@ -221,6 +248,55 @@ def _needs_canonical_host_prefix(canonical: str, host: str) -> bool:
     return first_segment.lower() != h.lower()
 
 
+def _compute_cross_repo_misconfig_risk(
+    plugin: MarketplacePlugin,
+    source: MarketplaceSource,
+    canonical: str,
+    dep_ref: DependencyReference | None,
+) -> CrossRepoMisconfigRisk | None:
+    """Identify the #1305 misconfiguration: cross-repo dict ``type: github``
+    source with bare ``repo`` on an enterprise GitHub-family marketplace.
+
+    Returns a :class:`CrossRepoMisconfigRisk` when **all** of:
+
+    - ``dep_ref`` is ``None`` (GitHub-family virtual-shorthand path; GitLab and
+      self-managed FQDNs build a structured ref upstream and sidestep the bug)
+    - ``plugin.source`` is a dict whose normalized type is ``github`` (other
+      dict types -- ``gitlab``, ``git-subdir`` -- hit the same auth-routing
+      bug but the "host-qualify with marketplace host" remediation only
+      matches operator intent for the GitHub family)
+    - the source is **not** an in-marketplace reference (PR #1292 already
+      backfills the host for those)
+    - ``_needs_canonical_host_prefix`` agrees the canonical is bare and the
+      host is GitHub-family enterprise (``*.ghe.com``; idempotent against
+      already host-qualified, URL, and SSH forms)
+    - the ``repo`` field is a non-empty ``owner/repo`` shorthand
+
+    Otherwise returns ``None``. Pure -- no logging, no side effects.
+    """
+    if dep_ref is not None:
+        return None
+    if not isinstance(plugin.source, dict):
+        return None
+    if _coerce_dict_plugin_type(plugin.source) != "github":
+        return None
+    if _is_in_marketplace_source(plugin, source):
+        return None
+    if not _needs_canonical_host_prefix(canonical, source.host):
+        return None
+    repo_field = plugin.source.get("repo", "")
+    if not isinstance(repo_field, str):
+        return None
+    bare = repo_field.strip().lstrip("/")
+    if "/" not in bare:
+        return None
+    return CrossRepoMisconfigRisk(
+        marketplace_host=source.host,
+        bare_repo_field=bare,
+        suggested_qualified_repo=f"{source.host}/{bare}",
+    )
+
+
 def _marketplace_https_git_url(source: MarketplaceSource) -> str:
     """HTTPS clone URL for the registered marketplace project (same project as ``marketplace.json``)."""
     segments = [p for p in f"{source.owner}/{source.repo}".split("/") if p]
@@ -607,6 +683,19 @@ def _emit_warning(msg: str) -> None:
             marketplace_name,
         )
 
+    # ---- Cross-repo misconfig sentinel (#1305) ----
+    # PR #1292's host backfill only covers in-marketplace sources. A cross-repo
+    # dict ``type: github`` source with a bare ``repo`` on an enterprise
+    # marketplace cannot be safely backfilled here -- the bare syntax also
+    # legitimately means "a github.com open-source dep from this enterprise
+    # marketplace" -- so the canonical stays bare and downstream auth routes at
+    # github.com. Attach a sentinel so the install command can emit an
+    # actionable hint ONLY when the package subsequently fails validation; the
+    # legitimate cross-host path validates fine and never sees the hint.
+    cross_repo_misconfig_risk = _compute_cross_repo_misconfig_risk(
+        plugin, source, canonical, dep_ref
+    )
+
     # ---- Raw ref override ----
     # When version_spec is provided it is treated as a raw git ref that
     # overrides whatever ref came from the marketplace source field.
@@ -674,5 +763,8 @@ def _emit_warning(msg: str) -> None:
         logger.debug("Shadow detection failed", exc_info=True)
 
     return MarketplacePluginResolution(
-        canonical=canonical, plugin=plugin, dependency_reference=dep_ref
+        canonical=canonical,
+        plugin=plugin,
+        dependency_reference=dep_ref,
+        cross_repo_misconfig_risk=cross_repo_misconfig_risk,
     )

tests/unit/commands/test_install_resolve_refs.py

@@ -280,3 +280,205 @@ def test_generated_entry_round_trips_via_from_apm_yml(self, tmp_path):
         assert ref.repo_url == "epm-ease/apm-registry"
         assert ref.virtual_path == "agents/ai-run-ba-flow"
         assert ref.is_virtual is True
+
+
+# ---------------------------------------------------------------------------
+# #1305 -- cross-repo bare-on-enterprise hint surfaces on validation failure
+# ---------------------------------------------------------------------------
+
+
+class TestResolvePackageReferencesCrossRepoMisconfigHint:
+    """When a marketplace resolution attaches a ``CrossRepoMisconfigRisk``
+    sentinel and the package later fails validation, an actionable hint must
+    be emitted via the logger. The legitimate cross-host path validates
+    successfully and never reaches the hint branch."""
+
+    @staticmethod
+    def _resolution_with_risk():
+        from apm_cli.marketplace.models import MarketplacePlugin
+        from apm_cli.marketplace.resolver import (
+            CrossRepoMisconfigRisk,
+            MarketplacePluginResolution,
+        )
+
+        plugin = MarketplacePlugin(
+            name="shared-tool",
+            source={
+                "type": "github",
+                "repo": "platform-team/shared-tool",
+                "path": "plugins/shared",
+            },
+        )
+        return MarketplacePluginResolution(
+            canonical="platform-team/shared-tool/plugins/shared",
+            plugin=plugin,
+            dependency_reference=None,
+            cross_repo_misconfig_risk=CrossRepoMisconfigRisk(
+                marketplace_host="corp.ghe.com",
+                bare_repo_field="platform-team/shared-tool",
+                suggested_qualified_repo=(
+                    "corp.ghe.com/platform-team/shared-tool"
+                ),
+            ),
+        )
+
+    @staticmethod
+    def _resolution_without_risk():
+        from apm_cli.marketplace.models import MarketplacePlugin
+        from apm_cli.marketplace.resolver import MarketplacePluginResolution
+
+        plugin = MarketplacePlugin(
+            name="shared-tool",
+            source="./plugins/shared",
+        )
+        return MarketplacePluginResolution(
+            canonical="myorg/my-marketplace/plugins/shared",
+            plugin=plugin,
+            dependency_reference=None,
+            cross_repo_misconfig_risk=None,
+        )
+
+    @patch("apm_cli.commands.install._validate_package_exists", return_value=False)
+    @patch("apm_cli.marketplace.resolver.resolve_marketplace_plugin")
+    @patch("apm_cli.marketplace.resolver.parse_marketplace_ref")
+    @patch("apm_cli.commands.install.DependencyReference")
+    def test_hint_emitted_on_validation_failure_with_risk(
+        self,
+        mock_dep_cls,
+        mock_parse_ref,
+        mock_resolve_mkt,
+        mock_validate,
+    ):
+        """Risk-bearing resolution that fails validation emits the hint."""
+        mock_parse_ref.return_value = ("shared-tool", "my-marketplace", None)
+        mock_resolve_mkt.return_value = self._resolution_with_risk()
+        ref = _make_dep_ref(
+            "platform-team/shared-tool/plugins/shared",
+            "github.com/platform-team/shared-tool/plugins/shared",
+        )
+        mock_dep_cls.parse.return_value = ref
+        mock_dep_cls.is_local_path.return_value = False
+        _disable_gitlab_direct_probe(mock_dep_cls)
+
+        logger = MagicMock()
+        logger.verbose = False
+
+        _resolve_package_references(
+            ["shared-tool@my-marketplace"],
+            [],
+            set(),
+            logger=logger,
+        )
+
+        # The hint must be emitted exactly once and include the
+        # actionable host-qualified suggestion.
+        info_calls = [c for c in logger.info.call_args_list]
+        assert len(info_calls) == 1
+        emitted = info_calls[0].args[0]
+        assert "shared-tool@my-marketplace" in emitted
+        assert "corp.ghe.com" in emitted
+        assert "platform-team/shared-tool" in emitted
+        assert (
+            "corp.ghe.com/platform-team/shared-tool" in emitted
+        )
+
+    @patch("apm_cli.commands.install._validate_package_exists", return_value=True)
+    @patch("apm_cli.marketplace.resolver.resolve_marketplace_plugin")
+    @patch("apm_cli.marketplace.resolver.parse_marketplace_ref")
+    @patch("apm_cli.commands.install.DependencyReference")
+    def test_hint_not_emitted_when_validation_passes_even_with_risk(
+        self,
+        mock_dep_cls,
+        mock_parse_ref,
+        mock_resolve_mkt,
+        mock_validate,
+    ):
+        """The legitimate cross-host path (validation succeeds) must NOT
+        emit the hint -- this is the entire reason the hint lives at the
+        failure boundary instead of at resolver time."""
+        mock_parse_ref.return_value = ("shared-tool", "my-marketplace", None)
+        mock_resolve_mkt.return_value = self._resolution_with_risk()
+        ref = _make_dep_ref(
+            "platform-team/shared-tool/plugins/shared",
+            "github.com/platform-team/shared-tool/plugins/shared",
+        )
+        mock_dep_cls.parse.return_value = ref
+        mock_dep_cls.is_local_path.return_value = False
+        _disable_gitlab_direct_probe(mock_dep_cls)
+
+        logger = MagicMock()
+        logger.verbose = False
+
+        _resolve_package_references(
+            ["shared-tool@my-marketplace"],
+            [],
+            set(),
+            logger=logger,
+        )
+
+        assert logger.info.call_args_list == []
+
+    @patch("apm_cli.commands.install._validate_package_exists", return_value=False)
+    @patch("apm_cli.marketplace.resolver.resolve_marketplace_plugin")
+    @patch("apm_cli.marketplace.resolver.parse_marketplace_ref")
+    @patch("apm_cli.commands.install.DependencyReference")
+    def test_no_hint_when_resolution_has_no_risk(
+        self,
+        mock_dep_cls,
+        mock_parse_ref,
+        mock_resolve_mkt,
+        mock_validate,
+    ):
+        """In-marketplace / non-enterprise resolutions carry no risk
+        sentinel; validation-fail must NOT print a hint."""
+        mock_parse_ref.return_value = ("shared-tool", "my-marketplace", None)
+        mock_resolve_mkt.return_value = self._resolution_without_risk()
+        ref = _make_dep_ref(
+            "myorg/my-marketplace/plugins/shared",
+            "github.com/myorg/my-marketplace/plugins/shared",
+        )
+        mock_dep_cls.parse.return_value = ref
+        mock_dep_cls.is_local_path.return_value = False
+        _disable_gitlab_direct_probe(mock_dep_cls)
+
+        logger = MagicMock()
+        logger.verbose = False
+
+        _resolve_package_references(
+            ["shared-tool@my-marketplace"],
+            [],
+            set(),
+            logger=logger,
+        )
+
+        assert logger.info.call_args_list == []
+
+    @patch("apm_cli.commands.install._validate_package_exists", return_value=False)
+    @patch("apm_cli.commands.install.DependencyReference")
+    def test_no_hint_for_plain_owner_repo_failure(
+        self,
+        mock_dep_cls,
+        mock_validate,
+    ):
+        """A bare ``owner/repo`` (no marketplace) that fails validation
+        must NOT trigger the hint -- the risk map is only populated by
+        marketplace resolutions."""
+        ref = _make_dep_ref(
+            "platform-team/shared-tool",
+            "github.com/platform-team/shared-tool",
+        )
+        mock_dep_cls.parse.return_value = ref
+        mock_dep_cls.is_local_path.return_value = False
+        _disable_gitlab_direct_probe(mock_dep_cls)
+
+        logger = MagicMock()
+        logger.verbose = False
+
+        _resolve_package_references(
+            ["platform-team/shared-tool"],
+            [],
+            set(),
+            logger=logger,
+        )
+
+        assert logger.info.call_args_list == []