feat: pluggable storage adapter — R2, GCS, S3-region config

[amal66]

Summary

Route every storage operation through a small StorageAdapter interface so the object-storage backend can be swapped without touching call sites. Cloudflare R2 stays the default and behaves exactly as before; a new Google Cloud Storage adapter (ADC auth) can be installed with one setStorageAdapter() call at startup. The S3 client region becomes configurable via R2_REGION (default "auto", unchanged).

Changes

• backend/src/lib/storage/adapter.ts — the StorageAdapter contract (upload / download / delete / list / getSignedUrl / checkReady).
• backend/src/lib/storage/r2.ts — R2StorageAdapter: the existing R2 code moved behind the interface. Same env vars, same "mike" bucket default, same error messages and null/empty fallbacks; region now reads R2_REGION (default "auto", the previous hardcoded value).
• backend/src/lib/storage/gcs.ts — GCSStorageAdapter: Google Cloud Storage via Application Default Credentials (GCS_BUCKET_NAME, GCS_PROJECT_ID, GCS_SIGNED_URL_TTL).
• backend/src/lib/storage.ts — now a thin public API: delegates uploadFile / downloadFile / deleteFile / listFiles / getSignedUrl to the active adapter, adds setStorageAdapter() + checkStorageReady(), and re-exports everything callers already import.
• backend/src/core/storagePaths.ts — the pure path/filename helpers (storageKey, buildContentDisposition, …) moved out of storage.ts; re-exported from lib/storage so no import changes anywhere.
• backend/tsconfig.json — exclude src/**/__tests__/** and *.test.ts from the build (tests run under vitest, not tsc).
• Tests: backend/src/lib/__tests__/storage.test.ts (25 tests, path/filename helpers), backend/src/lib/storage/__tests__/gcs.test.ts (16 tests, GCS adapter with a mocked SDK).
• backend/package.json / package-lock.json — add @google-cloud/storage@^7.19.0.

Why

Deploying anywhere other than Cloudflare requires either S3-compatible credentials or a fork of storage.ts. The adapter makes the backend portable: GCS out of the box, and any other backend (Supabase, local FS, S3) by implementing one interface. New runtime dependency: @google-cloud/storage@^7.19.0 (already shipped by the fork). Zero behavior change unless configured: the default adapter is R2 with identical env vars, defaults, and fallbacks — verified by reading each method against the previous storage.ts; R2_REGION and the GCS vars only take effect when explicitly set.

Testing

• npm install && npm run build (tsc) green on the branch as committed, from a clean node_modules.
• With the vitest harness (upstream-pr/test-harness) merged locally: npm test → 3 files, 53 tests passed (25 storage + 16 gcs from this branch, 12 pre-existing downloadTokens).

Provenance

All changes are mechanical ports of amal66/mike@origin/main (commit b3166dd): apps/api/src/lib/storage/{adapter,gcs,r2}.ts → backend/src/lib/storage/, apps/api/src/lib/storage.ts → backend/src/lib/storage.ts, apps/api/src/core/storagePaths.ts → backend/src/core/storagePaths.ts, plus their tests. Exceptions: (1) the fork reads config through its zod lib/env module, which this base lacks — env reads were translated to direct process.env access with the fork's defaults (R2_BUCKET_NAME/GCS_BUCKET_NAME → "mike", R2_REGION → "auto", GCS_SIGNED_URL_TTL → 3600), and the two tests' vi.mock("../env") blocks became plain process.env set/delete; (2) the tsconfig test-exclusion line, matching the other upstream-pr branches.

Credits & prior art

• @nforum (nforum/mike) — independently parallels this work: their fork added Google Cloud Storage support to Mike. Different implementation (this PR routes all backends through a StorageAdapter interface with R2 behavior preserved verbatim), same portability need.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CEguyEgXa9JjCciXCcVemC