Retry postinstall downloads on connect failure

[gavande1]

Related issues

• Fixes STU-1749

How AI was used in this PR

AI assisted with diagnosing the failure mode (undici's default 10s connect.timeout firing at the TCP/TLS handshake to wordpress.org, never reaching the body phase, and the script giving up after a single attempt) and drafted the implementation. I reviewed each change manually and ran lint + typecheck locally.

Proposed Changes

New shared lib — scripts/lib/with-retry.ts:

• withRetry< T >( name, fn, options? ) — generic retry helper with exponential backoff (1s → 2s) and up to 3 attempts.
• NonRetriableError — throw this from inside fn to opt an error out of retry.
• throwForHttpStatus( context, status, statusText? ) — maps response status to retriable vs non-retriable: 5xx and 429 retry; other 4xx (404, 401, 403, ...) throw NonRetriableError so we fail fast.
• sharedDispatcher — undici Agent with connect: { timeout: 10_000 } (matches Node's undici default; declared centrally so it can be tuned in one place if needed).

Per-attempt total connect budget is roughly 3 × 10s + (1s + 2s) ≈ 33s, which absorbs transient TLS handshake failures without bumping the per-attempt cap.

Adopted by scripts/download-wp-server-files.ts:

• fetchWithRetry artifact downloader (WordPress, SQLite integration, WP-CLI, sqlite-command, phpMyAdmin) now wraps the fetch in withRetry.
• fetchLatestGithubRelease is also wrapped in withRetry — the GitHub API call that resolves the sqlite-command URL no longer uses a 5s total timeout with no retries.

Adopted by scripts/download-language-packs.ts (sibling postinstall script that had its own near-identical retry helper):

• Removed the local recursive fetchWithRetry, MAX_RETRIES, INITIAL_RETRY_DELAY_MS.
• The translations API call and each per-locale zip download are now wrapped in withRetry individually, so JSON parsing and body streaming both benefit from retry.
• Inherits the same 4xx-fail-fast behavior.

Other notes:

• Error logging is single-sourced: the retry helper logs per-attempt failures (Attempt N/M failed ... Retrying in Xms); the script entry points already log the final thrown error before process.exit(1), so failures surface exactly once.
• undici is imported but kept as a transitive dependency (already pulled in by @octokit/core, hono, mime-db, and others) rather than declared in package.json, to keep this change minimal. Happy to pin it explicitly in a follow-up if reviewers prefer.

Testing Instructions

• Happy path — rm -rf wp-files && npx tsx ./scripts/download-wp-server-files.ts && npx tsx ./scripts/download-language-packs.ts should succeed and repopulate wp-files/.
• Retry on connect timeout — point wordpress.org at a blackholed IP to force connect-phase failures:

  sudo sh -c 'echo "192.0.2.1 wordpress.org" >> /etc/hosts'
  npx tsx ./scripts/download-wp-server-files.ts
  sudo sed -i '' '/192.0.2.1 wordpress.org/d' /etc/hosts
  

  Expect three [wordpress] Attempt N/3 failed: ... Retrying in Xms... lines followed by the final thrown error and a non-zero exit. The same blackhole trick on api.wordpress.org exercises the language-packs path.
• Fail-fast on 4xx — temporarily change a URL in either script to one that 404s and re-run. Expect a single attempt and an immediate Request failed with status code: 404 — no retries.
• GitHub API retry path — blackholing api.github.com should produce three [github:automattic/wp-cli-sqlite-command] Attempt N/3 failed ... lines before failing.
• npx eslint scripts/ — clean.
• npx tsc -p scripts/tsconfig.json --noEmit — clean.

Pre-merge Checklist

• Have you checked for TypeScript, React or other console errors?

[Copilot]

Pull request overview

This PR hardens the postinstall WordPress/server-files download script by introducing an undici-backed fetchWithRetry wrapper with a longer connect timeout, reducing failures caused by slow TCP/TLS handshakes during artifact downloads.

Changes:

• Add an undici Agent with a 15s connect timeout and a fetchWithRetry helper with exponential backoff retries.
• Route artifact downloads in downloadFile through fetchWithRetry instead of a single fetch.

---

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

[wpmobilebot]

📊 Performance Test Results

Comparing 6b9f9b0 vs trunk

app-size

Metric	trunk	6b9f9b0	Diff	Change
App Size (Mac)	1339.06 MB	1339.06 MB	+0.00 MB	⚪ 0.0%

site-editor

Metric	trunk	6b9f9b0	Diff	Change
load	1776 ms	1717 ms	59 ms	🟢 -3.3%

site-startup

Metric	trunk	6b9f9b0	Diff	Change
siteCreation	9595 ms	9591 ms	4 ms	⚪ 0.0%
siteStartup	4920 ms	4921 ms	+1 ms	⚪ 0.0%

---

Results are median values from multiple test runs.

Legend: 🟢 Improvement (faster) | 🔴 Regression (slower) | ⚪ No change (<50ms diff)