Support classic & fine-grained GitHub tokens with a guided, friendly setup UX

[altugank]

Summary

Make authenticating with GitHub effortless. WP Puller should fully and explicitly support both Personal Access Token types GitHub offers, and guide the user to create the right token with the right permissions — so connecting a private repo "just works" instead of failing with a confusing 404.

Current state

The plugin already accepts both token formats at the API level (includes/class-github-api.php → get_auth_header() sends Bearer <token> for both; includes/class-admin.php → get_pat_status() classifies ghp_ as classic and github_pat_ as fine-grained; tokens are encrypted at rest). What's missing is UX and validation: today it's a bare password field, and the most common failure is a valid-but-under-scoped token, which surfaces as a generic "Repository not found (404)".

The two token types and what they need

Type	Prefix	Required permissions
Classic PAT	ghp_	repo scope (or public_repo for public-only)
Fine-grained PAT	github_pat_	Repository access to the target repo + Contents: Read and Metadata: Read (Metadata is mandatory)

Goals

• A user with zero GitHub-API knowledge can connect a private repo in under a minute.
• It's always obvious which token type to use and which permissions to grant.
• Wrong/under-scoped tokens are caught before save with an actionable message — never a bare 404.

Scope / tasks

• Live token-type detection in the settings UI — show "Classic" / "Fine-grained" as the user types, with a short note on the permissions that type needs.
• Validate token + access on "Test", not just URL reachability: call the repo endpoint with the token and report specifically:
  • valid + has access ✅
  • token invalid/expired (401)
  • token lacks Contents/Metadata (fine-grained) or repo scope (classic) for this repo
• Guided token creation — "Create token" deep links pre-scoped where possible:
  • Classic: https://github.com/settings/tokens/new?scopes=repo&description=WP%20Puller
  • Fine-grained: link to the fine-grained creation page + an inline checklist of the exact permissions (URL pre-scoping isn't supported for fine-grained, so show the steps).
• Public vs private awareness — detect when the repo is public and make the token clearly optional; only require/prompt for a token when the repo is private.
• Friendly states — clear empty state, masked display (already done — keep it), and human error copy instead of raw GitHub messages.
• Centralize token classification in one helper so future GitHub token changes are a one-line update, and keep Bearer auth (works for both today).
• Keep tokens encrypted at rest and never logged (already true — add a regression note).

Acceptance criteria

• Connecting a private repo with a correctly-scoped token of either type succeeds end-to-end (test → save → check updates → update).
• An under-scoped or wrong-type token produces a specific, actionable message naming the missing permission.
• No token value ever appears in logs, debug output, or the rendered page source.

References

• wp-puller/includes/class-github-api.php — get_auth_header(), get_pat(), api_request() (the 404 branch already hints at this problem)
• wp-puller/includes/class-admin.php — ajax_test_connection(), get_pat_status()
• wp-puller/templates/admin-page.php — the Personal Access Token field