test(infra): add vitest unit tests and CI quality gates

[nasalehj]

Summary

Closes #10

The repository had no test infrastructure and no CI: package.json defined no test script, a search for *.test.*/*.spec.* found nothing, and .github/workflows did not exist. This PR introduces Vitest as the test runner, adds a test script, writes 76 unit tests across the seven modules the issue lists, and adds a GitHub Actions workflow that gates every push/PR on type-check, lint, test, and build with no required secrets.

Runner rationale — Vitest over Jest: it is TypeScript-native with zero config for unit tests (no ts-jest/babel ceremony), has jsdom built in (used here for the browser-API image tests, and a direct path to React Testing Library for the component tests the issue anticipates), and is significantly faster. It coexists with the existing Storybook scripts without touching the Next.js 14 build.

Why

Before this change the only verification a contributor could run was npm run type-check and npm run lint. Pure logic had zero regression protection: Stellar amount/address formatting, address validation, Stellar/Web3 error mapping, the TTL cache manager, the auth and UI stores, and the image-upload utilities were all unguarded, so behavioral fixes could regress silently and reviewers had no test output to judge changes on. The milestone issues (JWT verification, draft storage, wallet balance, env contract) each call for tests, and none could be written before this infrastructure existed.

What was built

File	What it contains
vitest.config.ts	Minimal config: include: ['tests/**/*.test.ts'], Node environment by default; browser-API tests opt into jsdom via a per-file // @vitest-environment jsdom pragma.
package.json	Adds "test": "vitest run" and devDependencies vitest + jsdom.
tests/stellar-formatting.test.ts	toStroops/fromStroops (incl. round-trip and error cases), formatAmount, formatCurrency, formatAsset (native + issued via the SDK Asset type), getBaseFee, formatFee, truncateAddress, parseAssetString — 13 tests.
tests/stellar-validation.test.ts	Valid/invalid public keys, secret keys, muxed addresses, and contract ids built from real SDK keypairs/StrKey encodings, plus getAddressType classification — 10 tests.
tests/stellar-errorHandler.test.ts	parseStellarError over JSON-RPC numeric codes, Horizon operation/transaction result codes, string codes, message-substring matching, and both fallbacks; isUserRejection — 10 tests.
tests/cacheManager.test.ts	Hits/misses/metrics, namespace isolation, TTL expiry (fake timers), LRU eviction, single-key and namespace invalidation, getOrSet caching + refresh-after-expiry, and metrics snapshot immutability — 10 tests.
tests/authStore.test.ts	Login/logout/setUser/setLoading/setTokens state transitions (persist middleware no-ops in Node since localStorage is unavailable) — 7 tests.
tests/uiStore.test.ts	Modal open/close, notification add (generated ids)/remove, sidebar toggle, theme, global loading — 7 tests.
tests/imageUpload.test.ts	jsdom environment: file type/size validation with custom limits, dimension validation with deterministic FileReader/Image stubs (within bounds, oversized, decode failure), preview URL create/revoke, formatFileSize, getFileExtension — 13 tests.
.github/workflows/ci.yml	GitHub Actions workflow: on push to main and on every PR, runs npm ci then npm run type-check, npm run lint, npm test, and npm run build (Node 22, npm cache). No secrets; any failing step fails the run and blocks the PR.
README.md	Documents the Vitest setup, the npm test command, and the CI workflow in the Testing section and scripts table.

The tests exercise the modules' real behavior — including error paths and edge cases (negative/NaN amounts, malformed addresses, TTL expiry, eviction, oversized images) — rather than implementation details, so they double as regression protection for the milestone's behavioral fixes.

Integration changes outside tests/

• lib/server/adminStore.ts, lib/server/draftStore.ts, lib/server/campaignDeployer.ts — pre-existing type errors on main (12 total) that made npm run type-check and npm run build fail before any test change, which would have made the new CI gates red out of the box. These are the same mechanical fixes as in PRs fix(env): reconcile env schema with reads and fail fast at boot #18 and fix(wallet): resolve balance from the configured network's Horizon #19 (issue Environment contract is drifting: lib/env.ts schema omits variables read elsewhere and assertEnv is never invoked #9 / Wallet balance is hardcoded to Horizon testnet: mainnet wallets always display a zero balance #8): noUncheckedIndexedAccess spread guards in the stores, and a port of campaignDeployer.ts from the removed @stellar/stellar-sdk v11 SorobanRpc/scval API to the v14 rpc/nativeToScVal/xdr API. Identical content across all three PRs merges cleanly regardless of order.
• tsconfig.json — "target": "ES2020" (was unset, defaulting to ES3, which broke BigInt literals in campaignDeployer.ts) and "allowImportingTsExtensions": true (safe with noEmit), identical to PRs fix(env): reconcile env schema with reads and fail fast at boot #18/fix(wallet): resolve balance from the configured network's Horizon #19.
• package-lock.json — vitest/jsdom dependency tree.

No other files were modified.

Acceptance criteria coverage

• npm test exists and runs green in a fresh clone with only npm install. (package.json — "test": "vitest run"; verified locally: npm test → 76/76 passing. Vitest/jsdom are declared devDependencies, so npm install is sufficient.)
• Unit tests cover lib/stellar/formatting.ts, lib/stellar/validation.ts, lib/stellar/errorHandler.ts, lib/cache/cacheManager.ts, store/authStore.ts, store/uiStore.ts, and utils/imageUpload.ts. (One test file per module in tests/ — 76 tests total.)
• A GitHub Actions workflow under .github/workflows/ runs type-check, lint, build, and test on push and pull request, with no required secrets. (.github/workflows/ci.yml — four steps on push to main and on pull_request; no secrets, only actions/checkout, actions/setup-node, npm ci.)
• The workflow is the only gate; test failures block the run. (Each quality command is a separate step; a failing step fails the job, so type-check, lint, test, or build failures all block the PR.)
• README documents how to run the tests. (README.md — Testing section with npm test and the CI description.)

Test plan

• npm test — 76/76 passing (76 new tests across 7 files)
• npm run type-check — no errors
• npm run lint — no warnings or errors
• npm run build — succeeds

Env vars / Notes

No new environment variables and no runtime dependency changes (vitest and jsdom are devDependencies only).

Notes:

• Runner choice: Vitest — TS-native with zero config, built-in jsdom, and a direct upgrade path to React Testing Library for the component tests explicitly anticipated by the issue. Jest would require a separate TS transform and slower cold runs.
• jsdom usage: only the image-upload tests opt into the jsdom environment (per-file pragma); everything else runs in Node. FileReader/Image are stubbed so dimension validation is deterministic (jsdom cannot decode real images).
• Deliberately untested: compressImage (canvas toBlob re-encoding needs a real rendering engine — out of the unit-test scope; the issue's out-of-scope section covers component/E2E tests), and the wallet/notification stores which were not listed in the acceptance criteria.
• Expected noise: the auth-store tests emit a zustand persist "storage is currently unavailable" warning in the Node environment (no localStorage); it is informational and the assertions pass.
• Merge notes: the test script (vitest run) supersedes the node --test script added in PRs fix(env): reconcile env schema with reads and fail fast at boot #18/fix(wallet): resolve balance from the configured network's Horizon #19 (issue Environment contract is drifting: lib/env.ts schema omits variables read elsewhere and assertEnv is never invoked #9/Wallet balance is hardcoded to Horizon testnet: mainnet wallets always display a zero balance #8) — all three PRs add the same devDependency-free runner setup otherwise, and the gate-unblocking changes in lib/server/* and tsconfig.json are byte-identical across all three.
• No data migrations involved.

[ibrahimmosouf-png]

LGTM