feat: bounded retry for transient API failures

[c-vigo]

Description

Adds bounded retry with exponential backoff for transient GitHub API failures. When the API returns transient errors (404, 5xx, 429, or 403 with rate-limit/abuse message), the action can automatically retry with configurable attempts instead of failing immediately.

Key additions:

• src/retry.ts — isTransientError, classifyError, calculateDelay, and withRetry utilities
• MAX_ATTEMPTS env var — controls retry count (default 1 = no retries for backward compatibility)
• All GitHub API calls in commitViaAPI (getBranchInfo, getCommit, createTree, createCommit, updateBranch) wrapped in withRetry
• Exponential backoff with jitter to avoid thundering herd

Related Issue(s)

Closes #20

Type of Change

• New feature (non-breaking change which adds functionality)
• Bug fix (non-breaking change which fixes an issue)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Test updates

Changes Made

• Added src/retry.ts with RetryConfig, isTransientError, classifyError, calculateDelay, and withRetry
• Extended CommitOptions with maxAttempts, logger, baseDelayMs, maxDelayMs
• Wrapped getBranchInfo, getCommit, createTree, createCommit, updateBranch in withRetry
• Added MAX_ATTEMPTS env parsing in commit-runner.ts (invalid values clamped to 1)
• Unit tests for retry logic, commit retry behavior, and MAX_ATTEMPTS parsing
• README documentation for MAX_ATTEMPTS and CommitOptions retry options
• Rebuilt dist artifacts

Testing

• Tests pass locally (npm test)
• Manual testing performed (describe below)

Manual Testing Details

Unit tests cover: isTransientError (404, 5xx, 429, 403 rate-limit message), classifyError, calculateDelay (backoff, jitter, max cap), withRetry (success, exhaust, non-transient no-retry, logger), commit retry behavior (maxAttempts 1/2/3), and MAX_ATTEMPTS env parsing.

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have updated the documentation accordingly (README.md, CONTRIBUTE.md, etc.)
• I have updated the CHANGELOG.md in the [Unreleased] section
• My changes generate no new warnings or errors
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published

Additional Notes

• Default maxAttempts: 1 preserves existing behavior (no retries) so this is backward compatible
• Transient errors: 404, 5xx, 429, and 403 when the error message indicates rate limit / abuse (Octokit RequestError exposes this in the message string)
• CHANGELOG.md should be updated before or after merge (as noted in COMMIT_PLAN.md)

[Copilot]

Pull request overview

Adds bounded retry with exponential backoff (and jitter) around GitHub REST calls to reduce flakiness from transient API errors, and wires it into the action via a MAX_ATTEMPTS env var / CommitOptions configuration. The PR also updates the commit implementation to reduce REST call volume by inlining text file content into createTree, adds binary detection + tree batching, and refreshes docs/tests/dist artifacts.

Changes:

• Introduces src/retry.ts (isTransientError, classifyError, calculateDelay, withRetry) and wraps key API operations in commitViaAPI with retry.
• Adds MAX_ATTEMPTS parsing in commit-runner.ts and passes retry config/logging into commitViaAPI.
• Optimizes tree creation (inline content for UTF-8 text, binary detection, chained/batched createTree) and expands unit tests + docs + compiled dist.

Reviewed changes

Copilot reviewed 9 out of 32 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/retry.ts	New retry utilities (classification, backoff, bounded retry wrapper).
src/commit.ts	Wraps core GitHub API operations with retry; adds tree creation optimizations and helpers.
src/commit-runner.ts	Parses MAX_ATTEMPTS and passes retry config/logger to commitViaAPI.
src/tests/unit/retry.test.ts	Unit tests for transient classification, delay calculation, and retry behavior.
src/tests/unit/commit.test.ts	Expanded tests for new tree behavior, binary detection, and commit retries.
src/tests/unit/commit-runner.test.ts	Tests MAX_ATTEMPTS parsing/clamping behavior.
src/tests/setup.ts	Extends mocked fs with sync fd APIs for binary detection tests.
dist/src/retry.js.map	Built sourcemap for retry module.
dist/src/retry.js	Built JS for retry module.
dist/src/retry.d.ts.map	Built TS declaration sourcemap for retry.
dist/src/retry.d.ts	Built TS declarations for retry.
dist/src/commit.js.map	Updated built sourcemap for commit module changes.
dist/src/commit.js	Updated built JS for commit module changes (retry + tree optimization).
dist/src/commit.d.ts.map	Updated built TS declaration sourcemap for commit module.
dist/src/commit.d.ts	Updated built TS declarations for commit module public surface changes.
dist/src/commit-runner.js.map	Updated built sourcemap for runner changes.
dist/src/commit-runner.js	Updated built JS for runner changes (MAX_ATTEMPTS parsing).
dist/src/commit-runner.d.ts.map	Updated built TS declaration sourcemap for runner.
dist/src/commit-runner.d.ts	Updated built TS declarations for runner docs/header.
dist/src/tests/unit/retry.test.js.map	Built sourcemap for retry unit tests.
dist/src/tests/unit/retry.test.js	Built JS for retry unit tests.
dist/src/tests/unit/retry.test.d.ts.map	Built TS declaration sourcemap for retry unit tests.
dist/src/tests/unit/retry.test.d.ts	Built TS declarations for retry unit tests.
dist/src/tests/unit/commit.test.js	Updated built JS for commit unit tests.
dist/src/tests/unit/commit-runner.test.js.map	Updated built sourcemap for runner unit tests.
dist/src/tests/unit/commit-runner.test.js	Updated built JS for runner unit tests.
dist/src/tests/setup.js.map	Updated built sourcemap for test setup changes.
dist/src/tests/setup.js	Updated built JS for test setup changes.
dist/index.js	Updated bundled action output including retry + runner + commit changes.
README.md	Documents MAX_ATTEMPTS and new module exports; updates usage example.
CHANGELOG.md	Adds [Unreleased] entries describing new functionality/behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.