Merge pull request #18 from link-foundation/issue-17-5aba117748c0

feat: use gh CLI as default backend with API fallback

Author: konard

.changeset/gh-default-with-api-fallback.md

@@ -0,0 +1,12 @@
+---
+'gh-load-pull-request': minor
+---
+
+Use gh CLI as default backend with API fallback
+
+- By default, the tool now uses the `gh` CLI to fetch PR data when available
+- Automatically falls back to GitHub REST API (Octokit) if gh CLI is not installed or not authenticated
+- Added `--force-api` flag to force using the GitHub API instead of gh CLI
+- Added `--force-gh` flag to force using gh CLI (fails if not available)
+- Added new CI/CD job to test both gh CLI and API modes
+- Improved verbose logging to show which backend is being used

.github/workflows/release.yml

@@ -113,14 +113,63 @@ jobs:
 
       - name: Run tests
         run: bun test
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  # Test both gh CLI and API modes explicitly
+  test-modes:
+    name: Test Modes (gh CLI and API)
+    runs-on: ubuntu-latest
+    needs: [changeset-check]
+    if: always() && (github.event_name == 'push' || needs.changeset-check.result == 'success')
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Test gh CLI mode
+        run: |
+          # Test with gh CLI (should work since GH_TOKEN is set)
+          bun run src/gh-load-pull-request.mjs link-foundation/gh-load-pull-request#2 --force-gh --format json > gh-output.json
+          echo "gh CLI mode test passed"
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Test API mode
+        run: |
+          # Test with API mode
+          bun run src/gh-load-pull-request.mjs link-foundation/gh-load-pull-request#2 --force-api --format json > api-output.json
+          echo "API mode test passed"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Compare outputs
+        run: |
+          # Parse and compare key fields
+          GH_NUMBER=$(cat gh-output.json | bun -e "console.log(JSON.parse(await Bun.stdin.text()).pullRequest.number)")
+          API_NUMBER=$(cat api-output.json | bun -e "console.log(JSON.parse(await Bun.stdin.text()).pullRequest.number)")
+
+          if [ "$GH_NUMBER" != "$API_NUMBER" ]; then
+            echo "PR number mismatch: gh=$GH_NUMBER api=$API_NUMBER"
+            exit 1
+          fi
+
+          echo "Both modes produce consistent output for PR #$GH_NUMBER"
 
   # Release - only runs on main after tests pass (for push events)
   release:
     name: Release
-    needs: [lint, test]
+    needs: [lint, test, test-modes]
     # Use always() to ensure this job runs even if changeset-check was skipped
     # This is needed because lint/test jobs have a transitive dependency on changeset-check
-    if: always() && github.ref == 'refs/heads/main' && github.event_name == 'push' && needs.lint.result == 'success' && needs.test.result == 'success'
+    if: always() && github.ref == 'refs/heads/main' && github.event_name == 'push' && needs.lint.result == 'success' && needs.test.result == 'success' && needs.test-modes.result == 'success'
     runs-on: ubuntu-latest
     # Permissions required for npm OIDC trusted publishing
     permissions:

README.md

@@ -73,10 +73,45 @@ chmod +x gh-load-pull-request.mjs
 Usage: gh-load-pull-request <pr-url> [options]
 
 Options:
-  -t, --token    GitHub personal access token (optional for public PRs)
-  -o, --output   Output file path (default: stdout)
-  -h, --help     Show help
-  --version      Show version number
+  -t, --token         GitHub personal access token (optional for public PRs)
+  -o, --output        Output directory (creates pr-<number>/ subfolder)
+  --format            Output format: markdown, json (default: markdown)
+  --download-images   Download embedded images (default: true)
+  --include-reviews   Include PR reviews (default: true)
+  --force-api         Force using GitHub API instead of gh CLI
+  --force-gh          Force using gh CLI, fail if not available
+  -v, --verbose       Enable verbose logging
+  -h, --help          Show help
+  --version           Show version number
+```
+
+## Backend Modes
+
+The tool supports two backend modes for fetching PR data:
+
+### 1. gh CLI Mode (Default)
+
+By default, the tool uses the [GitHub CLI](https://cli.github.com/) (`gh`) to fetch PR data. This is the recommended mode as it:
+
+- Uses your existing `gh` authentication
+- Doesn't require managing tokens separately
+- Works seamlessly with GitHub Enterprise
+
+### 2. API Mode (Fallback)
+
+If `gh` CLI is not available or not authenticated, the tool automatically falls back to using the GitHub REST API via Octokit. You can also force this mode with `--force-api`.
+
+### Controlling Backend Mode
+
+```bash
+# Use default mode (gh CLI with API fallback)
+gh-load-pull-request owner/repo#123
+
+# Force gh CLI mode (fails if gh is not available)
+gh-load-pull-request owner/repo#123 --force-gh
+
+# Force API mode (useful for testing or when gh has issues)
+gh-load-pull-request owner/repo#123 --force-api
 ```
 
 ## Input Formats
@@ -152,14 +187,23 @@ gh-load-pull-request https://github.com/facebook/react/pull/28000
 gh-load-pull-request facebook/react#28000
 
 # Save to file
-gh-load-pull-request facebook/react#28000 -o react-pr-28000.md
+gh-load-pull-request facebook/react#28000 -o ./output
 
 # Download private PR using gh CLI auth
 gh-load-pull-request myorg/private-repo#42
 
 # Download with explicit token
 gh-load-pull-request myorg/repo#123 --token ghp_your_token_here
 
+# Force using GitHub API instead of gh CLI
+gh-load-pull-request owner/repo#123 --force-api
+
+# Output as JSON
+gh-load-pull-request owner/repo#123 --format json
+
+# Verbose mode for debugging
+gh-load-pull-request owner/repo#123 -v
+
 # Pipe to other tools (e.g., AI for review)
 gh-load-pull-request owner/repo#123 | claude-analyze
 ```