[FEATURE] build_error_context [i] port hint should name a concrete verification command + doc link

[edenfunf]

Follow-up from PR #788 review panel -- devx-ux-expert finding #4 ("`[i]` hint actionability ~70%").

Is your feature request related to a problem? Please describe.

The `[i]` hint appended by `AuthResolver.build_error_context` when `dep_ref.port` is set names the right suspect but not the next action. Current output (`src/apm_cli/core/auth.py:428-429` on main):

```
[i] Host 'bitbucket.example.com:7999' -- verify your credential helper stores per-port entries (some helpers key by host only).
```

A user who hits this has two immediate questions the hint does not answer:

1. How do I verify that? Nothing tells them which command to run against which helper; they have to translate "stores per-port entries" into GCM / osxkeychain / libsecret / gh-auth specifics themselves.
2. Where do I read more? The public docs already have the helper compatibility table (`docs/src/content/docs/getting-started/authentication.md` -- added in fix(auth): thread dep_ref.port into credential resolution (#785) #788), but the hint does not link to it.

Net effect: roughly 70% actionable. Names the problem; stops short of naming the remediation.

Describe the solution you'd like

Rewrite the hint to include a concrete verification command for the most common helper (`git credential-manager`) and anchor at the new docs section:

```
[i] Host 'bitbucket.example.com:7999' -- this helper may key by host only.
Verify with: printf 'protocol=https\nhost=bitbucket.example.com:7999\n\n' | git credential fill
See: https://microsoft.github.io/apm/getting-started/authentication/#custom-port-hosts-and-per-port-credentials
```

Rationale:

• `git credential fill` is the helper-agnostic entry point every credential helper implements -- it reproduces exactly what APM does internally, so the user can see what their helper returns for the same (host, port) pair.
• The docs URL points to the per-helper compatibility table already in tree, so users who need per-helper specifics (GCM vs. osxkeychain vs. libsecret vs. gh auth) land directly on it.
• Matches the wire-format precedent set by the PR fix(install): warn when --allow-protocol-fallback reuses a custom port across schemes (#786) #789 cross-protocol warning, which also emits a `See: ` line.

Describe alternatives you've considered

• Leave as-is. Current wording is correct; just under-actionable. Acceptable if we expect most users to reach the docs via the `--verbose` diagnostics. Reviewer panel rated this ~70% actionable, so there is room.
• Helper-specific guidance inline. Emit different advice for GCM vs. osxkeychain vs. libsecret. Rejected: the helper is opaque to APM at emission time, and the helper-compatibility table in docs is the right place for that detail -- not a three-line terminal hint.
• Separate `--diagnose-credentials` subcommand. Bigger surface than this finding warrants.

Additional context

• Docs anchor already exists: https://microsoft.github.io/apm/getting-started/authentication/#custom-port-hosts-and-per-port-credentials
• Mirror skill entry also exists at `packages/apm-guide/.apm/skills/apm-usage/authentication.md` (added in PR fix(auth): thread dep_ref.port into credential resolution (#785) #788's polish push), so the same command example stays discoverable when users are assisted by the in-repo APM usage skill.
• Scope-limited: one string in `build_error_context` + one test update (`tests/unit/test_auth.py::TestBuildErrorContextWithPort` already asserts the `per-port` marker; expand to assert the `git credential fill` substring and the docs URL).

Refs

• PR #788 (auth port threading -- introduced the hint)
• PR #788 review verdict, finding Add ARM64 Linux support to CI/CD pipeline #4
• Sibling: #798 (other PR fix(auth): thread dep_ref.port into credential resolution (#785) #788 follow-up)

[edenfunf]

@danielmeppiel -- before I write this, wanted to sanity-check the wording with you since it's pure UX copy and you'll have a much better feel for what our users expect.

Two shapes I was considering:

(A) single-line + docs URL:

[i] Host 'bitbucket.example.com:7999' -- confirm your helper keys by host:port (docs: https://microsoft.github.io/apm/getting-started/authentication/#custom-port-hosts-and-per-port-credentials).

(B) three lines with a git credential fill reproducer:

[i] Host 'bitbucket.example.com:7999' -- this helper may key by host only.
    Verify with: printf 'protocol=https\nhost=bitbucket.example.com:7999\n\n' | git credential fill
    See: https://microsoft.github.io/apm/getting-started/authentication/#custom-port-hosts-and-per-port-credentials

I was tentatively leaning (A) because the other hints in build_error_context are all single-line, and the docs anchor already has the per-helper compatibility table -- so one link gives both diagnosis and remediation in a single jump. But (B) has the real advantage of putting a reproducer right at the point of failure, which is closer to what your original finding called for.

Happy either way -- your read of the user journey is better than mine. Could you nudge me one direction or the other?

[github-actions]

Triage decision

accept

Proposed labels

area/cli
area/docs-site
type/feature
status/accepted
priority/low

Milestone

0.9.4

Suggested next action

Update build_error_context in auth.py to include a scheme-appropriate connectivity check command (ssh -T git@host for SSH, curl -sI (host/redacted) for HTTPS/HTTP) and link to the auth troubleshooting doc (creating that page if it does not exist).

Suggested issue comment

Thanks for this follow-up -- actionable error messages are a core DX goal for APM, and the PR #788 review panel finding is right that naming the suspect is only ~70% of the job.

The improvement is concrete: when `dep_ref.port` is set and the `[i]` hint fires, append a scheme-appropriate verification command:

- SSH (port 22 or custom): `ssh -T git@<host>` (or `ssh -p <port> git@<host>` for non-default ports)
- HTTPS: `curl -sI https://<host>` (or `curl -sI https://<host>:<port>`)
- HTTP: `curl -sI (redacted)

The doc link target should be the auth troubleshooting section of the APM docs. If that page does not exist yet, the implementing PR should create a minimal troubleshooting guide at `docs/src/content/docs/guides/troubleshooting/auth.md` that covers the common connectivity patterns -- that page will also be useful for future error messages.

One constraint: the command string must stay within printable ASCII and must not include any user credentials or tokens (per the cross-platform encoding rule and the credential safety policy).

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The user task is "diagnose why APM cannot connect to my dependency host." The current [i] hint names the right variable (the port) but does not tell the user what to do next. Adding a concrete verification command closes the actionability gap and aligns with the cargo / pip mental model of "the tool should tell you the next command to run, not just what went wrong."

Supply Chain Security Expert -- Risk-Surface Reviewer

No risk-surface implication. The change is entirely within error message formatting. The implementation must not embed user credentials or tokens in the suggested command string.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- edenfunf is a returning contributor (CONTRIBUTOR association) with meaningful prior project interactions; warmth tuning for a first-time contributor is not needed.

Python Architect -- Architecture Reviewer

Not activated -- the change is localized to build_error_context in auth.py (add a scheme-to-command lookup table, format the command string). No cross-cutting design decision, interface change, or migration boundary is involved.

Doc Writer -- Documentation Reviewer

The feature explicitly mentions a doc link. If an auth troubleshooting guide page does not already exist in docs/src/content/docs/, the implementing PR should create one. area/docs-site is included as a secondary area to ensure the implementing PR is reminded of this requirement. The suggested command strings should use the same vocabulary as the existing auth guide sections.

APM CEO -- Triage Arbiter

Pure DX polish with a docs creation dependency. Accept at priority/low for 0.9.4: the improvement is valuable but not blocking any user workflow. If the troubleshooting doc page does not exist, the PR should create a minimal one -- this is a good opportunity to establish that page as a reference point for future error message links.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": null,
  "areas": ["area/cli", "area/docs-site"],
  "type": "type/feature",
  "status": "status/accepted",
  "priority": "priority/low",
  "preserved_labels": [],
  "milestone": "0.9.4",
  "next_action": "Update build_error_context to append a scheme-appropriate connectivity check command and link to the auth troubleshooting doc (create the page if it does not exist).",
  "comment_markdown": "Thanks for this follow-up -- actionable error messages are a core DX goal for APM, and the PR #788 review panel finding is right that naming the suspect is only ~70% of the job.\n\nThe improvement is concrete: when `dep_ref.port` is set and the `[i]` hint fires, append a scheme-appropriate verification command:\n\n- SSH (port 22 or custom): `ssh -T git@<host>` (or `ssh -p <port> git@<host>` for non-default ports)\n- HTTPS: `curl -sI https://<host>` (or `curl -sI https://<host>:<port>`)\n- HTTP: `curl -sI (redacted) doc link target should be the auth troubleshooting section of the APM docs. If that page does not exist yet, the implementing PR should create a minimal troubleshooting guide at `docs/src/content/docs/guides/troubleshooting/auth.md` that covers the common connectivity patterns -- that page will also be useful for future error messages.\n\nOne constraint: the command string must stay within printable ASCII and must not include any user credentials or tokens (per the cross-platform encoding rule and the credential safety policy)."
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · ● 2.3M · ◷