Fix organization loading error for PATs without read:org permission

[Copilot]

Problem

Users with GitHub Personal Access Tokens (PATs) that have repository access (repo scope for classic tokens, or Contents/Pull requests permissions for fine-grained tokens) but lack organization listing permissions were encountering a blocking error when trying to create a new DAK:

Error: "Error loading organizations"

This occurred because:

1. The getUserOrganizations() API call requires the read:org scope (classic tokens) or Members: Read-only permission (fine-grained tokens)
2. When GitHub API returned 403/401 due to missing permission, the code threw an exception that blocked the entire workflow
3. The error message was generic and didn't explain what permission was missing or that users could continue anyway
4. Documentation incorrectly implied that read:org was required for basic functionality

Solution

This PR implements graceful permission handling and improves documentation clarity:

1. Graceful Error Handling

Modified getUserOrganizations() in src/services/githubService.js to:

• Catch 403/401 permission errors specifically
• Return an empty array instead of throwing (users can still work with their personal account and WHO organization)
• Only throw errors for actual issues like network problems (preserving retry functionality)
• Log helpful console warning explaining the missing permission

// Before: Always threw error, blocking users
catch (error) {
  console.error('Failed to fetch organizations:', error);
  throw error;  // ❌ User blocked
}

// After: Handle permission errors gracefully
catch (error) {
  console.error('Failed to fetch organizations:', error);
  
  if (error.status === 403 || error.status === 401) {
    console.warn('Token does not have permission to list organizations...');
    return [];  // ✅ User can continue
  }
  
  throw error;  // Still throw for network errors to allow retry
}

2. Improved Error Messages

Updated OrganizationSelection.js to show context-aware error messages:

• Explains exactly what permission is missing
• Specifies the scope name for both classic and fine-grained tokens
• Reassures users they can still proceed with their personal account or WHO organization

Before: "Failed to fetch organizations. Please check your connection and try again."

After: "Unable to list your organizations. Your Personal Access Token needs the 'read:org' scope (classic tokens) or 'Members: Read-only' permission (fine-grained tokens) to list organizations. You can still use your personal account or select WHO."

3. Documentation Clarity

Updated documentation to clarify that organization listing permission is optional:

• README.md: Added note explaining read:org / Members: Read-only is only needed for listing organizations
• PATSetupInstructions.js: Added info note during token setup explaining optional permissions
• PATLogin.js: Updated error messages to focus on core required permissions

All documentation now clearly distinguishes between:

• Required permissions: repo (classic) or Contents + Pull requests (fine-grained) - for editing DAK content
• Optional permissions: read:org (classic) or Members: Read-only (fine-grained) - only if you want to see organizations you're a member of

4. Visual Enhancement

Added .info-note CSS class in PATSetupInstructions.css for displaying informational messages with proper styling (blue background, clear formatting) to distinguish from warnings and errors.

5. Comprehensive Testing

Added 5 new tests in src/services/githubService.test.js:

• ✅ Successful organization retrieval with proper permissions
• ✅ Graceful 403 handling (returns empty array)
• ✅ Graceful 401 handling (returns empty array)
• ✅ Error throwing for non-permission errors (network issues)
• ✅ Authentication requirement validation

All tests passing, no existing tests broken.

User Experience Impact

Before Fix

1. User creates PAT with repo scope only
2. User logs in successfully
3. User clicks "Create New DAK"
4. ❌ BLOCKED with error: "Error loading organizations"

After Fix

1. User creates PAT with repo scope only
2. User logs in successfully
3. User clicks "Create New DAK"
4. Sees clear message about optional permission
5. User selects personal account or WHO
6. ✅ User successfully proceeds with DAK creation

Benefits

• Better UX: Users aren't blocked by missing optional permission
• Clear Guidance: Error messages explain exactly what's needed and why
• Reduced Friction: Users can start working immediately with minimal permissions
• Progressive Enhancement: Users can add read:org later if they need organization listing
• Documentation Clarity: Users understand permission requirements before creating tokens
• Fully Backward Compatible: Users with read:org permission experience no change in behavior

Files Changed

• src/services/githubService.js - Graceful error handling
• src/components/OrganizationSelection.js - Improved error message
• README.md - Clarified optional permission
• src/components/PATSetupInstructions.js - Added info note
• src/components/PATSetupInstructions.css - Info note styling
• src/components/PATLogin.js - Updated error message
• src/services/githubService.test.js - Added comprehensive tests

Related Issue

Fixes issue reported by @costateixeira regarding PAT permissions and organization loading errors when creating new DAKs.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Bug]: issue loading organizations when creating a new DAK</issue_title>
<issue_description>### What happened?

After entering a PAT and selecting my personal github account, when I am on the screen that says Select Destination for New DAK, I see Error loading organizations.
Are my PAT permissions sufficient? the documentation doesn't say what permissions to include in the PAT.
Can you see and fix this if there is such a scenario that can cause such an error?

Expected behavior

I should not get the error or should have a way to get past it.

Steps to reproduce

login with PAt (classic, access to public repos
Select Profile (personal)
Create new dak
Select Organization
</issue_description>

Comments on the Issue (you are @copilot in this section)

@costateixeira @copilot can you improve the documentation for the PATs and tell me what is the error or fix it?

Fixes #1033

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.