fix: Handle HTTP 502 errors for large gist uploads

[konard]

Summary

Fixes #19 - Gist upload fails for ~50MB+ files with HTTP 502, but tool reports success.

Root Cause Analysis

While GitHub documents a 100MB limit for gist files, the REST API has practical limitations:

• Large POST requests (>25-50MB) cause HTTP 502 errors due to server timeout/payload limits
• The safe threshold matches the web interface limit of 25MB

Changes Made

1. Fix Success Detection Bug

• Validate gist URL is present and valid before reporting success
• Throw error with stderr details when gist creation fails

2. Lower Gist Threshold

• Changed GITHUB_GIST_FILE_LIMIT from 100MB to 25MB
• This matches the web interface limit and avoids HTTP 502 errors

3. Implement Automatic Fallback

• When gist upload fails, automatically fall back to repository mode
• Unless --only-gist is specified, in which case the error is thrown

4. Add Self-Test Feature

• --test / -t: Run full self-test (1MB, 10MB, 24MB files)
• --quick / -q: Run quick test (1MB file only)
• Tests actual upload functionality on user's machine

5. Add Test Utilities

• scripts/generate-test-file.mjs: Generate text files of specific sizes
• Case study documentation in docs/case-studies/issue-19/

Test Results

File Size	Expected Strategy	Result
1 KB	gist	✅ gist
1 MB	gist	✅ gist
24 MB	gist	✅ gist
26 MB	repo	✅ repo

Usage Examples

# Normal upload - files ≤25MB go to gist, >25MB go to repo
gh-upload-log file.log

# Self-test to verify everything works
gh-upload-log --test

# Quick test (1MB only)
gh-upload-log --quick

# Force gist mode (will error if upload fails)
gh-upload-log large-file.log --only-gist

# Force repository mode
gh-upload-log file.log --only-repository

Breaking Changes

• Files between 25-100MB will now use repository mode instead of gist mode
• This is a fix, not a breaking change, as these files were failing with HTTP 502 before

---

🤖 Generated with Claude Code

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

• Public pricing estimate: $7.248191 USD
• Calculated by Anthropic: $4.862610 USD
• Difference: $-2.385581 (-32.91%)
  📎 Log file uploaded as GitHub Gist (857KB)
  🔗 View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.