Phase 3: GitHub API client + all shared commands (Go port)

This PR implements the core GitHub API client and all shared gei
subcommands in Go, building on the project skeleton (PR 1) and
HTTP/auth foundation (PR 2).

## GitHub API client (pkg/github/)

- Custom GraphQL client with pagination, secondary rate limit
  detection and retry, and navigateJSON() dot-path traversal
- 32+ migration API methods via google/go-github REST client:
  organization, repository, team, mannequin, migration lifecycle
- Comprehensive models (models.go) for all API response types

## Shared command infrastructure (internal/cmdutil/)

- UserError type for user-friendly error messages
- Flag validators: ValidatePaired, ValidateAtLeastOne, ValidateExactlyOne
- Migration status constants and classifier (pkg/migration/)

## Commands (cmd/gei/)

- wait-for-migration: poll migration status with configurable interval
- abort-migration: cancel in-progress migrations
- download-logs: fetch and save migration log archives
- grant-migrator-role / revoke-migrator-role: manage migration permissions
- create-team: create GitHub teams with idempotent slug handling
- generate-mannequin-csv: export mannequin data to CSV
- reclaim-mannequin: reclaim mannequins from CSV or individual args

## Supporting packages

- pkg/download/: migration log download service with temp file cleanup
- pkg/mannequin/: mannequin reclamation service with CSV parsing
- pkg/version/: version checker against GitHub releases
- pkg/status/: GitHub status page availability check

## Testing

- 170+ tests across all packages, all passing with -race
- External test package convention (package foo_test)
- httptest-based test servers for API client tests

## Tooling

- golangci-lint v2 configured, 0 issues
- Go 1.25.4 added to mise.toml alongside dotnet 8.0.410
- Go binary names added to .gitignore

Author: offbyone

.gitignore

@@ -360,6 +360,11 @@ MigrationBackup/
 /src/OctoshiftCLI.IntegrationTests/Properties/launchSettings.json
 /src/ado2gh/Properties/launchSettings.json
 
+# Go binaries (built from cmd/)
+/gei
+/ado2gh
+/bbs2gh
+
 # Go coverage reports
 coverage/
 *.out

.golangci.yml

@@ -1,76 +1,94 @@
 # golangci-lint configuration for gh-gei Go port
 # See https://golangci-lint.run/usage/configuration/
+version: "2"
 
 run:
   timeout: 5m
   tests: true
   modules-download-mode: readonly
 
+formatters:
+  enable:
+    - gofmt
+    - goimports
+    - gofumpt
+
 linters:
   enable:
-    - gofmt         # Checks formatting
-    - goimports     # Checks imports
     - govet         # Reports suspicious constructs
     - errcheck      # Checks for unchecked errors
-    - staticcheck   # Static analysis
+    - staticcheck   # Static analysis (includes gosimple, stylecheck)
     - unused        # Checks for unused code
-    - gosimple      # Simplify code
     - ineffassign   # Detects ineffectual assignments
-    - typecheck     # Type-checks code
     - bodyclose     # Checks for HTTP response body close
     - noctx         # Finds HTTP requests without context
     - misspell      # Finds commonly misspelled English words
     - unconvert     # Removes unnecessary type conversions
     - goconst       # Finds repeated strings that could be constants
     - gocyclo       # Computes cyclomatic complexities
-    - gofumpt       # Stricter gofmt
     - revive        # Fast, configurable, extensible linter
     - gosec         # Security-focused linter
     - errname       # Checks error naming
     - errorlint     # Finds misuses of errors
-    - exportloopref # Checks for pointers to enclosing loop variables
     - whitespace    # Detects leading/trailing whitespace
 
-linters-settings:
-  gocyclo:
-    min-complexity: 15
-  goconst:
-    min-len: 3
-    min-occurrences: 3
-  misspell:
-    locale: US
-  revive:
-    rules:
-      - name: exported
-        severity: warning
-        disabled: false
-      - name: package-comments
-        severity: warning
-        disabled: false
-  gosec:
-    excludes:
-      - G104  # Audit errors not checked (too noisy)
+  settings:
+    gocyclo:
+      min-complexity: 15
+    goconst:
+      min-len: 3
+      min-occurrences: 3
+    misspell:
+      locale: US
+    revive:
+      rules:
+        - name: exported
+          severity: warning
+          disabled: false
+        - name: package-comments
+          severity: warning
+          disabled: false
+    gosec:
+      excludes:
+        - G104  # Audit errors not checked (too noisy)
 
-issues:
-  exclude-use-default: false
-  max-issues-per-linter: 0
-  max-same-issues: 0
-  
-  exclude-rules:
-    # Exclude some linters from running on tests files
-    - path: _test\.go
-      linters:
-        - gocyclo
-        - errcheck
-        - gosec
-    
-    # Exclude error checks in main.go files (handled by cobra)
-    - path: cmd/.*/main\.go
-      text: "Error return value"
-      linters:
-        - errcheck
+  exclusions:
+    presets:
+      - comments
+      - common-false-positives
+      - legacy
+      - std-error-handling
+    rules:
+      # Exclude some linters from running on tests files
+      - path: _test\.go
+        linters:
+          - gocyclo
+          - errcheck
+          - gosec
+          - revive
+      # Exclude error checks in main.go files (handled by cobra)
+      - path: cmd/.*/main\.go
+        text: "Error return value"
+        linters:
+          - errcheck
+      # Unused functions in skeleton main.go files will be wired up in future PRs
+      - path: cmd/.*/main\.go
+        linters:
+          - unused
+      # G101 false positives on template constant names containing "Password", "Secret", etc.
+      - path: pkg/scriptgen/templates\.go
+        text: "G101"
+        linters:
+          - gosec
+      # Cyclomatic complexity for generate-script command will be addressed when refactoring
+      - path: cmd/gei/generate_script\.go
+        linters:
+          - gocyclo
 
 output:
-  format: colored-line-number
-  print-issued-lines: true
-  print-linter-name: true
+  formats:
+    text:
+      path: stdout
+      colors: true
+      print-issued-lines: true
+      print-linter-name: true

cmd/ado2gh/main.go

@@ -2,13 +2,22 @@ package main
 
 import (
 	"context"
+	"net/http"
 	"os"
+	"strings"
 
 	"github.com/github/gh-gei/pkg/env"
 	"github.com/github/gh-gei/pkg/logger"
+	"github.com/github/gh-gei/pkg/status"
+	versionpkg "github.com/github/gh-gei/pkg/version"
 	"github.com/spf13/cobra"
 )
 
+// contextKey is an unexported type for context keys in this package.
+type contextKey string
+
+const loggerKey contextKey = "logger"
+
 var (
 	version = "dev"
 	verbose bool
@@ -25,11 +34,16 @@ func newRootCmd() *cobra.Command {
 		Use:   "ado2gh",
 		Short: "Azure DevOps to GitHub migration CLI",
 		Long:  "Automate end-to-end Azure DevOps Repos to GitHub migrations.",
-		PersistentPreRun: func(cmd *cobra.Command, args []string) {
+		PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
 			log := logger.New(verbose)
-			ctx := context.WithValue(cmd.Context(), "logger", log)
+			ctx := context.WithValue(cmd.Context(), loggerKey, log)
 			cmd.SetContext(ctx)
 			log.Debug("Execution started")
+
+			checkVersion(ctx, log)
+			checkGitHubStatus(ctx, log)
+
+			return nil
 		},
 		SilenceUsage:  true,
 		SilenceErrors: true,
@@ -64,7 +78,7 @@ func newRootCmd() *cobra.Command {
 }
 
 func getLogger(cmd *cobra.Command) *logger.Logger {
-	if log, ok := cmd.Context().Value("logger").(*logger.Logger); ok {
+	if log, ok := cmd.Context().Value(loggerKey).(*logger.Logger); ok {
 		return log
 	}
 	return logger.New(false)
@@ -76,17 +90,41 @@ func getEnvProvider() *env.Provider {
 
 func checkVersion(ctx context.Context, log *logger.Logger) {
 	envProvider := getEnvProvider()
-	if envProvider.SkipVersionCheck() == "true" || envProvider.SkipVersionCheck() == "1" {
+	skip := envProvider.SkipVersionCheck()
+	if strings.EqualFold(skip, "true") || skip == "1" {
 		log.Info("Skipped latest version check due to GEI_SKIP_VERSION_CHECK environment variable")
 		return
 	}
-	log.Info("You are running ado2gh CLI version %s", version)
+
+	checker := versionpkg.NewChecker(&http.Client{}, log, version)
+	isLatest, err := checker.IsLatest(ctx)
+	if err != nil {
+		log.Debug("Version check failed: %v", err)
+		return
+	}
+
+	if !isLatest {
+		latest, _ := checker.GetLatestVersion(ctx)
+		log.Info("New version available: %s", latest)
+		log.Info("You are running ado2gh CLI version %s", version)
+	}
 }
 
 func checkGitHubStatus(ctx context.Context, log *logger.Logger) {
 	envProvider := getEnvProvider()
-	if envProvider.SkipStatusCheck() == "true" || envProvider.SkipStatusCheck() == "1" {
+	skip := envProvider.SkipStatusCheck()
+	if strings.EqualFold(skip, "true") || skip == "1" {
 		log.Info("Skipped GitHub status check due to GEI_SKIP_STATUS_CHECK environment variable")
 		return
 	}
+
+	count, err := status.GetUnresolvedIncidentsCount(ctx, &http.Client{}, "https://www.githubstatus.com")
+	if err != nil {
+		log.Debug("GitHub status check failed: %v", err)
+		return
+	}
+
+	if count > 0 {
+		log.Warning("GitHub is currently experiencing %d incident(s). Check https://www.githubstatus.com for details.", count)
+	}
 }

cmd/bbs2gh/main.go

@@ -2,13 +2,22 @@ package main
 
 import (
 	"context"
+	"net/http"
 	"os"
+	"strings"
 
 	"github.com/github/gh-gei/pkg/env"
 	"github.com/github/gh-gei/pkg/logger"
+	"github.com/github/gh-gei/pkg/status"
+	versionpkg "github.com/github/gh-gei/pkg/version"
 	"github.com/spf13/cobra"
 )
 
+// contextKey is an unexported type for context keys in this package.
+type contextKey string
+
+const loggerKey contextKey = "logger"
+
 var (
 	version = "dev"
 	verbose bool
@@ -25,11 +34,16 @@ func newRootCmd() *cobra.Command {
 		Use:   "bbs2gh",
 		Short: "Bitbucket Server to GitHub migration CLI",
 		Long:  "Migrate repositories from Bitbucket Server and Data Center to GitHub Enterprise Cloud.",
-		PersistentPreRun: func(cmd *cobra.Command, args []string) {
+		PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
 			log := logger.New(verbose)
-			ctx := context.WithValue(cmd.Context(), "logger", log)
+			ctx := context.WithValue(cmd.Context(), loggerKey, log)
 			cmd.SetContext(ctx)
 			log.Debug("Execution started")
+
+			checkVersion(ctx, log)
+			checkGitHubStatus(ctx, log)
+
+			return nil
 		},
 		SilenceUsage:  true,
 		SilenceErrors: true,
@@ -57,7 +71,7 @@ func newRootCmd() *cobra.Command {
 }
 
 func getLogger(cmd *cobra.Command) *logger.Logger {
-	if log, ok := cmd.Context().Value("logger").(*logger.Logger); ok {
+	if log, ok := cmd.Context().Value(loggerKey).(*logger.Logger); ok {
 		return log
 	}
 	return logger.New(false)
@@ -69,17 +83,41 @@ func getEnvProvider() *env.Provider {
 
 func checkVersion(ctx context.Context, log *logger.Logger) {
 	envProvider := getEnvProvider()
-	if envProvider.SkipVersionCheck() == "true" || envProvider.SkipVersionCheck() == "1" {
+	skip := envProvider.SkipVersionCheck()
+	if strings.EqualFold(skip, "true") || skip == "1" {
 		log.Info("Skipped latest version check due to GEI_SKIP_VERSION_CHECK environment variable")
 		return
 	}
-	log.Info("You are running bbs2gh CLI version %s", version)
+
+	checker := versionpkg.NewChecker(&http.Client{}, log, version)
+	isLatest, err := checker.IsLatest(ctx)
+	if err != nil {
+		log.Debug("Version check failed: %v", err)
+		return
+	}
+
+	if !isLatest {
+		latest, _ := checker.GetLatestVersion(ctx)
+		log.Info("New version available: %s", latest)
+		log.Info("You are running bbs2gh CLI version %s", version)
+	}
 }
 
 func checkGitHubStatus(ctx context.Context, log *logger.Logger) {
 	envProvider := getEnvProvider()
-	if envProvider.SkipStatusCheck() == "true" || envProvider.SkipStatusCheck() == "1" {
+	skip := envProvider.SkipStatusCheck()
+	if strings.EqualFold(skip, "true") || skip == "1" {
 		log.Info("Skipped GitHub status check due to GEI_SKIP_STATUS_CHECK environment variable")
 		return
 	}
+
+	count, err := status.GetUnresolvedIncidentsCount(ctx, &http.Client{}, "https://www.githubstatus.com")
+	if err != nil {
+		log.Debug("GitHub status check failed: %v", err)
+		return
+	}
+
+	if count > 0 {
+		log.Warning("GitHub is currently experiencing %d incident(s). Check https://www.githubstatus.com for details.", count)
+	}
 }