sync: check token scopes up front, skip projects when read:project is missing

A token with repo but not read:project made the projects v2 GraphQL query
fail field-by-field ("the 'createdAt' field requires ['read:project']"),
emitting one error per scope-gated field on every run.

Add Client.Scopes() (reads X-OAuth-Scopes; reports unknown for fine-grained /
app tokens) and a featureScopes table checked before sync. Projects is now
skipped with a single clear message when its scope is absent.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: mevdschee

internal/github/client.go

@@ -21,6 +21,10 @@ const (
 type Client struct {
 	token  string
 	client *http.Client
+
+	scopes        []string
+	scopesKnown   bool
+	scopesFetched bool
 }
 
 func NewClient(token string) *Client {
@@ -30,6 +34,44 @@ func NewClient(token string) *Client {
 	}
 }
 
+// Scopes returns the OAuth scopes granted to the token, as reported by the
+// X-OAuth-Scopes header on an authenticated request. The boolean is false when
+// the token does not report scopes — fine-grained PATs and GitHub App
+// installation tokens omit the header — in which case the caller must not
+// infer that any scope is missing. The result is fetched once and cached.
+func (c *Client) Scopes() ([]string, bool) {
+	if c.scopesFetched {
+		return c.scopes, c.scopesKnown
+	}
+	c.scopesFetched = true
+
+	req, err := http.NewRequest("GET", API+"/", nil)
+	if err != nil {
+		return nil, false
+	}
+	req.Header.Set("Accept", "application/vnd.github+json")
+	req.Header.Set("Authorization", "Bearer "+c.token)
+
+	resp, err := c.client.Do(req)
+	if err != nil {
+		return nil, false
+	}
+	defer resp.Body.Close()
+	io.Copy(io.Discard, resp.Body)
+
+	header, ok := resp.Header["X-Oauth-Scopes"]
+	if !ok {
+		return nil, false
+	}
+	c.scopesKnown = true
+	for _, part := range strings.Split(strings.Join(header, ","), ",") {
+		if s := strings.TrimSpace(part); s != "" {
+			c.scopes = append(c.scopes, s)
+		}
+	}
+	return c.scopes, true
+}
+
 var linkNextRe = regexp.MustCompile(`<([^>]+)>;\s*rel="next"`)
 
 func apiError(url string, status int, body []byte) error {

internal/sync/run.go

@@ -18,22 +18,28 @@ import (
 func Run(c *github.Client, s *store.Store, owner, repo, since, syncStart string) ([]hooks.Event, error) {
 	var events []hooks.Event
 
+	skip := checkScopes(c)
+
 	if err := Labels(c, s, owner, repo); err != nil {
 		log.Printf("Warning: %v", err)
 	}
 	if err := Milestones(c, s, owner, repo); err != nil {
 		log.Printf("Warning: %v", err)
 	}
-	issueProjects, projectEvents, err := Projects(c, s, owner, repo, since)
-	if err != nil {
-		log.Printf("Warning: %v", err)
+	var issueProjects map[int64][]string
+	if !skip["projects"] {
+		ip, projectEvents, err := Projects(c, s, owner, repo, since)
+		if err != nil {
+			log.Printf("Warning: %v", err)
+		}
+		issueProjects = ip
+		events = append(events, projectEvents...)
 	}
 	issueEvents, err := Issues(c, s, owner, repo, since, issueProjects)
 	if err != nil {
 		log.Printf("Warning: %v", err)
 	}
 	events = append(events, issueEvents...)
-	events = append(events, projectEvents...)
 
 	releaseEvents, err := Releases(c, s, owner, repo)
 	if err != nil {

internal/sync/scopes.go

@@ -0,0 +1,57 @@
+package sync
+
+import (
+	"log"
+	"strings"
+
+	"github.com/mevdschee/github-export/internal/github"
+)
+
+// featureScopes maps each optional feature to the OAuth scopes that unlock it
+// (holding any one is enough). Features absent from this map need only `repo`,
+// without which nothing syncs at all. Projects v2 is the odd one out: GitHub
+// rejects the query field-by-field ("the 'createdAt' field requires one of the
+// following scopes: ['read:project']") when the scope is missing, so we skip
+// the feature up front instead of letting it spew one error per field.
+var featureScopes = map[string][]string{
+	"projects": {"read:project", "project"},
+}
+
+// checkScopes inspects the token's granted scopes, logs them, and returns the
+// set of features to skip because none of their accepted scopes is present.
+// It returns nil (skip nothing) for tokens that do not report scopes —
+// fine-grained PATs and GitHub App tokens — since their permissions are not
+// expressed as a scope list and must not be second-guessed.
+func checkScopes(c *github.Client) map[string]bool {
+	granted, known := c.Scopes()
+	if !known {
+		return nil
+	}
+	if len(granted) == 0 {
+		log.Println("Token scopes: (none)")
+	} else {
+		log.Printf("Token scopes: %s", strings.Join(granted, ", "))
+	}
+
+	have := make(map[string]bool, len(granted))
+	for _, s := range granted {
+		have[s] = true
+	}
+
+	skip := map[string]bool{}
+	for feature, accepted := range featureScopes {
+		ok := false
+		for _, s := range accepted {
+			if have[s] {
+				ok = true
+				break
+			}
+		}
+		if !ok {
+			skip[feature] = true
+			log.Printf("Skipping %s: token lacks the %q scope (add it with: gh auth refresh -s %s)",
+				feature, accepted[0], accepted[0])
+		}
+	}
+	return skip
+}