Display required PAT scopes proactively during connection creation

[Copilot]

PAT scope hints were only surfaced via the interactive masked prompt, leaving users who supply tokens via --token, .devlake.env, or env vars with no visibility into required scopes until a connection test fails with an opaque API error.

Changes

• cmd/configure_connections.go / cmd/configure_full.go: Print Required PAT scopes: <hint> immediately after the 📡 Creating … connection… step header, regardless of token source.

• cmd/connection_types.go: Added scopeHintSuffix() helper on ConnectionDef; both TestConnection failure paths (network error and API-reported failure) now append a 💡 Ensure your PAT has these scopes: … hint to the returned error.

• cmd/configure_connection_test_cmd.go: test subcommand prints the scope hint after ❌ Connection test failed.

• cmd/connection_types_test.go: Added TestAvailablePluginsScopeHints asserting all available plugins have non-empty RequiredScopes and ScopeHint.

• README.md: Updated configure connection step list and configure connection test failure output example.

Example output

📡 Creating GitHub Copilot connection...
   Required PAT scopes: manage_billing:copilot, read:org (+ read:enterprise for enterprise metrics)
   ✅ Connection test passed
   ✅ Created GitHub Copilot connection (ID=2)

On failure:

❌ Connection test failed: 401 Unauthorized
   💡 Ensure your PAT has these scopes: manage_billing:copilot, read:org (+ read:enterprise for enterprise metrics)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Display required PAT scopes proactively during connection creation</issue_title>
<issue_description>## Summary
Required PAT scopes (e.g. manage_billing:copilot for gh-copilot, repo + read:org for github) are only shown when the token is entered via the interactive masked prompt — source #4 in the resolution chain. If the token comes from --token, .devlake.env, or $GITHUB_TOKEN/$GH_TOKEN, the user never sees what scopes are needed until the connection test fails with a potentially unclear API error.

Current Behavior

• ScopeHint is passed to token.Resolve() → only printed in promptMasked() (stderr)
• Tokens from flag/envfile/env skip the hint entirely
• On connection test failure, the error comes from the DevLake API and may not clearly indicate which scopes are missing

Proposed Changes

1. Always display required scopes at connection creation time

Print ScopeHint right after the connection creation step header, regardless of token source:

📡 Creating GitHub Copilot connection...
   Required PAT scopes: manage_billing:copilot, read:org (+ read:enterprise for enterprise metrics)
   ✅ Connection test passed
   ✅ Created GitHub Copilot connection (ID=2)

2. Enrich test failure messages with scope hints

When TestConnection fails, append a hint:

gh-copilot connection test failed: 401 Unauthorized
   💡 Ensure your PAT has these scopes: manage_billing:copilot, read:org

3. (Stretch) Distinguish classic vs fine-grained PAT permissions

Classic PATs and fine-grained PATs use different permission models. Consider adding a ClassicScopes / FineGrainedPermissions distinction to ConnectionDef:

Plugin	Classic PAT	Fine-grained PAT
github	repo, read:org, read:user	Repository: Read, Organization: Read
gh-copilot	manage_billing:copilot, read:org	Organization: Copilot Business (read)

Changes

• In buildAndCreateConnection(): print def.ScopeHint before testing/creating
• In buildAndCreateConnection(): on test failure, append scope hint to error message
• Optionally extend ConnectionDef with ClassicScopes and FineGrainedHint fields

Acceptance Criteria

• Required PAT scopes displayed during connection creation regardless of token source
• Connection test failures include a hint about required scopes
• Works for all available plugins (github, gh-copilot)
• configure full flow also shows scopes per connection</issue_description>

<agent_instructions>Display required PAT scopes proactively during connection creation, regardless of how the token was resolved.

Key Files to Modify

1. cmd/connection_types.go

The ConnectionDef struct already has RequiredScopes []string and ScopeHint string fields. These are populated for both github and gh-copilot plugins. No changes needed here unless you want to add ClassicScopes/FineGrainedHint for the stretch goal.

2. cmd/configure_connections.go — runConfigureConnections()

After the "Creating {plugin} connection..." line and BEFORE the test/create call, print the required scopes:

fmt.Printf("\n📡 Creating %s connection...\n", def.DisplayName)
if def.ScopeHint != "" {
    fmt.Printf("   Required PAT scopes: %s\n", def.ScopeHint)
}

3. cmd/connection_types.go — buildAndCreateConnection()

When TestConnection fails, enrich the error message with the scope hint:

if !testResult.Success {
    hint := ""
    if def.ScopeHint != "" {
        hint = fmt.Sprintf("\n   💡 Ensure your PAT has these scopes: %s", def.ScopeHint)
    }
    return nil, fmt.Errorf("%s connection test failed: %s%s", def.DisplayName, testResult.Message, hint)
}

Also when TestConnection returns an error (network/HTTP error), append the hint:

if err != nil {
    hint := ""
    if def.ScopeHint != "" {
        hint = fmt.Sprintf("\n   💡 Ensure your PAT has these scopes: %s", def.ScopeHint)
    }
    return nil, fmt.Errorf("%s connection test failed: %w%s", def.DisplayName, err, hint)
}

4. cmd/configure_full.go

Same pattern — when creating connections in the full flow, print scope hints before each connection creation step.

5. cmd/configure_connection_test_cmd.go

When the test command fails, include the scope hint if available:

After fmt.Printf("❌ Connection test failed: %s\n", msg), add:

def := FindConnectionDef(plugin)
if def != nil && def.ScopeHint != "" {
    fmt.Printf("   💡 Ensure your PAT has these scopes: %s\n", def.ScopeHint)
}

6. README.md

Update the configure connection section to mention that required PAT scopes are now displayed during connection creation.

7. Tests

• Add a test in cmd/connection_types_test.go verifying that all available plugins have non-empty ScopeHint and RequiredScopes
• Test the enriched error message ...

• Fixes Display required PAT scopes proactively during connection creation #17

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

[Copilot]

Pull request overview

This PR enhances the visibility of required PAT (Personal Access Token) scopes during connection creation by displaying them proactively, regardless of how the token was provided (flag, env file, or interactive prompt). Previously, scope hints were only shown during interactive token entry, leaving users who supplied tokens via other methods unaware of requirements until connection tests failed.

Changes:

• Displays required PAT scopes immediately after the "Creating connection..." step header in all connection creation flows
• Enriches connection test failure messages with scope hint reminders
• Adds test coverage to ensure all available plugins define required scopes

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
cmd/connection_types.go	Added scopeHintSuffix() helper method and enriched test failure error messages with scope hints
cmd/configure_connections.go	Displays scope hints after connection creation step header
cmd/configure_full.go	Displays scope hints after connection creation step header in full configuration flow
cmd/configure_connection_test_cmd.go	Displays scope hints after connection test failures
cmd/connection_types_test.go	Added test to verify all available plugins have RequiredScopes and ScopeHint defined
README.md	Updated documentation to reflect scope hint display behavior and updated step numbering