DX: Improve auth error messages and sparse checkout token consistency #469
Description
Context
During the RCA for #425 (GitHub App token shadowed by apm-action), we identified several APM CLI improvements that would help users diagnose auth failures faster and improve token handling consistency.
These are not root-cause bugs (the primary fix is in apm-action), but they would significantly improve the developer experience when auth issues occur.
1. Misleading "transitive dep" error message for direct dependencies
File: src/apm_cli/commands/install.py (download_callback, ~line 1204)
When a direct dependency fails to download, the error message says:
Failed to resolve transitive dep my-org/my-repo (via my-package-name)
The parent_chain for depth-1 dependencies includes the dependency's own display name via get_ancestor_chain(), making it appear as if there is a transitive dependency chain when there is none. This confused the user in #425 who saw "2 packages failed" and thought APM had introduced new transitive dependency resolution.
Proposed fix: Distinguish direct vs transitive failures. Use "Failed to download dependency" for direct deps, and "Failed to resolve transitive dep ... (via ...)" only for depth > 1.
2. Sparse checkout auth inconsistency
File: src/apm_cli/deps/github_downloader.py (~line 1462)
_try_sparse_checkout() uses self.github_token directly to build the auth URL, while _clone_with_fallback() uses resolve_for_dep() to get a per-dependency token. In multi-org setups with per-org tokens (via GITHUB_APM_PAT_<ORG>), sparse checkout could use the wrong token.
Proposed fix: Align _try_sparse_checkout to use resolve_for_dep() for token resolution, matching _clone_with_fallback.
3. Error deduplication for clone failures
When a clone fails, the diagnostic output reports the same failure from two perspectives -- the download callback error and the install error -- without linking them. In the #425 case, this showed "2 packages failed" when there was really just one clone failure.
Proposed fix: Consider deduplicating or linking related errors in the diagnostic output so users understand these are the same root failure.
Priority
Low -- these are DX improvements, not blockers. The root cause fix (#425) is in apm-action.