Merge pull request #734 from Anasabubakar/chore/fresh-clone-install-build-test

Fresh-clone reliability: install/build/test, coverage gates, logging/error tracking, dep audits, env docs, CI typecheck, UI file splits

Author: K1NGD4VID

.env.example

@@ -84,6 +84,14 @@ NEXT_PUBLIC_POOL_CONTRACT_ID=CAKEWH7SJCXGV2MH2WZYIX3QDPTSSBQFXYVYBOWAGLNBBZMPLE2
 #   Required: yes
 NEXT_PUBLIC_ESCROW_CONTRACT_ID=CAJWGUKDTTC3SKN4RAAY72J4DVIIYSCFHX6GIMNTT22ABMISJK4GBCEH
 
+# NEXT_PUBLIC_AGENT_REGISTRY_CONTRACT_ID
+#   Layer: frontend, SDK
+#   Type: Stellar contract ID string
+#   Required: no (until Underwrite's agent-registry contract is deployed;
+#            mirrors the backend AGENT_REGISTRY_CONTRACT below)
+#   Default: none
+NEXT_PUBLIC_AGENT_REGISTRY_CONTRACT_ID=
+
 # ── Asset configuration (frontend / SDK) ─────────────────────────────────────
 # NEXT_PUBLIC_USDC_ISSUER
 #   Layer: frontend, SDK
@@ -189,6 +197,17 @@ DATABASE_URL=postgresql://postgres:postgres@localhost:5432/trusttrove?sslmode=di
 #   Source: Neon direct connection, migration tooling, or admin tasks
 DATABASE_URL_UNPOOLED=
 
+# TEST_DATABASE_URL
+#   Layer: indexer/backend (test-only)
+#   Type: PostgreSQL connection URL
+#   Required: no
+#   Default: none — when unset, the Go integration tests in indexer/db and
+#            indexer/listener skip instead of failing (`go test ./...`
+#            passes either way). Set this to a disposable Postgres instance
+#            to actually exercise those tests and their coverage locally.
+#   Source: local .env or CI service container
+TEST_DATABASE_URL=
+
 # API_PORT
 #   Layer: indexer/backend
 #   Type: integer port
@@ -213,6 +232,26 @@ PORT=
 #   Source: local .env or deployment env
 INDEXER_POLL_INTERVAL_MS=5000
 
+# INDEXER_MIGRATIONS_DIR
+#   Layer: indexer/backend
+#   Type: absolute or relative directory path
+#   Required: no
+#   Default: auto-detected relative to the running binary/working directory
+#            (indexer/db/migrations); only needed when that auto-detection
+#            doesn't apply, e.g. running the compiled binary from an unusual
+#            working directory or in CI.
+#   Source: local .env or deployment env
+INDEXER_MIGRATIONS_DIR=
+
+# APP_ENV
+#   Layer: indexer/backend
+#   Type: string enum: development | production
+#   Required: no
+#   Default: development
+#   Source: local .env or deployment env. In production, JWT_SECRET and
+#           SERVER_SEED below become required instead of auto-generated.
+APP_ENV=development
+
 # JWT_SECRET
 #   Layer: indexer/backend
 #   Type: string secret
@@ -229,6 +268,18 @@ JWT_SECRET=change_me_before_production
 #   Source: local .env or deployment env
 JWT_EXPIRY_HOURS=24
 
+# SERVER_SEED
+#   Layer: indexer/backend
+#   Type: string secret (Stellar keypair seed, starts with 'S')
+#   Required: yes in production; leave empty for local/development — the
+#            indexer generates a valid random keypair automatically at
+#            startup when this is unset. Unlike JWT_SECRET, this is parsed
+#            as a real Stellar strkey immediately, so a placeholder string
+#            like "change_me" fails startup instead of just being insecure.
+#   Default: none (auto-generated when empty and APP_ENV != production)
+#   Source: generated Stellar keypair in local/deployment secret manager
+SERVER_SEED=
+
 # ALLOWED_ORIGINS
 #   Layer: indexer/backend
 #   Type: comma-separated URLs
@@ -237,6 +288,30 @@ JWT_EXPIRY_HOURS=24
 #   Source: Render or local .env
 ALLOWED_ORIGINS=https://trustrove.vercel.app,http://localhost:3000
 
+# CORS_ALLOWED_ORIGINS
+#   Layer: indexer/backend
+#   Type: comma-separated URLs
+#   Required: no
+#   Default: only read when ALLOWED_ORIGINS above is unset
+#   Source: alternate name for ALLOWED_ORIGINS; set one or the other, not both
+CORS_ALLOWED_ORIGINS=
+
+# RATE_LIMIT_RPS
+#   Layer: indexer/backend
+#   Type: integer requests per second (per client)
+#   Required: no
+#   Default: 10
+#   Source: local .env or deployment env
+RATE_LIMIT_RPS=10
+
+# SENTRY_DSN
+#   Layer: indexer/backend
+#   Type: URL string (Sentry project DSN)
+#   Required: no
+#   Default: none — leave empty to disable error tracking entirely
+#   Source: Sentry project settings, set as a secret in the deployment env
+SENTRY_DSN=
+
 # ── Frontend-only deployment settings ────────────────────────────────────────
 # NEXT_PUBLIC_API_BASE_URL
 #   Layer: frontend
@@ -245,3 +320,22 @@ ALLOWED_ORIGINS=https://trustrove.vercel.app,http://localhost:3000
 #   Default: http://localhost:8080 if the frontend API helper is left unconfigured
 #   Source: Vercel env or local .env.local
 NEXT_PUBLIC_API_BASE_URL=http://localhost:8080
+
+# NEXT_PUBLIC_APP_URL
+#   Layer: frontend
+#   Type: URL string
+#   Required: no
+#   Default: http://localhost:3000, used to build absolute links (e.g. shared
+#            invoice URLs) when the request's own origin isn't available
+#   Source: Vercel env or local .env.local
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+
+# ── Ambient / CI-provided (do not set by hand) ───────────────────────────────
+# CI
+#   Layer: frontend (apps/web/playwright.config.ts)
+#   Type: boolean-ish string, any non-empty value is truthy
+#   Required: no
+#   Default: unset locally; automatically set to "true" by GitHub Actions and
+#            most other CI providers. Only affects Playwright's own retry/
+#            worker/dev-server-reuse behavior — leave unset in .env.local.
+CI=

.github/dependabot.yml

@@ -0,0 +1,21 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "npm"
+    directory: "/apps/web"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "npm"
+    directory: "/packages/sdk"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "gomod"
+    directory: "/indexer"
+    schedule:
+      interval: "weekly"

.github/workflows/ci.yml

@@ -29,6 +29,16 @@ jobs:
       - name: Install Dependencies
         run: pnpm install --frozen-lockfile
 
+      - name: Typecheck
+        run: pnpm typecheck
+
+      - name: Audit npm dependencies
+        # pnpm-workspace.yaml's auditConfig.ignoreGhsas lists the specific,
+        # already-triaged advisories this ignores (next 14->15 and toml 3->4,
+        # both needing a major-version bump, not a patch override) and why.
+        # Any new high/critical advisory not on that list fails the build.
+        run: pnpm audit --audit-level=high
+
       - name: Build Packages (SDK & Web App)
         run: pnpm build
         env:
@@ -50,14 +60,29 @@ jobs:
     name: Verify Go Indexer & API
     runs-on: ubuntu-latest
 
+    services:
+      postgres:
+        image: postgres:15-alpine
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: trusttrove_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+
     steps:
       - name: Checkout Code
         uses: actions/checkout@v4
 
       - name: Setup Go
         uses: actions/setup-go@v5
         with:
-          go-version: "1.22"
+          go-version: "1.25"
 
       - name: Get Dependencies
         run: |
@@ -72,7 +97,32 @@ jobs:
       - name: Test Go Services
         run: |
           cd indexer
-          go test -v ./...
+          go test -v -coverprofile=coverage.out ./...
+        env:
+          TEST_DATABASE_URL: postgresql://postgres:postgres@localhost:5432/trusttrove_test?sslmode=disable
+          INDEXER_MIGRATIONS_DIR: ${{ github.workspace }}/indexer/db/migrations
+
+      - name: Enforce indexer/db coverage threshold
+        run: |
+          cd indexer
+          go test -covermode=atomic -coverprofile=db-coverage.out ./db/... \
+            | tee /dev/stderr \
+            | grep -oE 'coverage: [0-9.]+% of statements' \
+            | grep -oE '[0-9.]+' \
+            > /tmp/db_coverage_pct.txt
+          pct=$(cat /tmp/db_coverage_pct.txt)
+          echo "indexer/db statement coverage: ${pct}%"
+          awk -v pct="$pct" 'BEGIN { exit !(pct >= 70) }' \
+            || (echo "indexer/db coverage ${pct}% is below the required 70% threshold" && exit 1)
+        env:
+          TEST_DATABASE_URL: postgresql://postgres:postgres@localhost:5432/trusttrove_test?sslmode=disable
+          INDEXER_MIGRATIONS_DIR: ${{ github.workspace }}/indexer/db/migrations
+
+      - name: Vulnerability scan (govulncheck)
+        run: |
+          go install golang.org/x/vuln/cmd/govulncheck@latest
+          cd indexer
+          govulncheck ./...
 
       - name: Lint Go Services
         run: |

.gitignore

@@ -17,6 +17,10 @@ indexer/indexer.exe
 *.wasm
 *.exe
 
+# Test coverage output
+coverage/
+*.out
+
 # Debug logs
 npm-debug.log*
 yarn-debug.log*

README.md

@@ -72,7 +72,7 @@ Yield distributes to LP shares
 | Wallet          | Freighter browser extension                                                               |
 | Payments        | USDC on Stellar                                                                           |
 | SDK             | Custom TypeScript contract client wrappers                                                |
-| Indexer         | Go 1.22, chi router, pgx v5                                                               |
+| Indexer         | Go 1.25, chi router, pgx v5                                                               |
 | Database        | PostgreSQL 15                                                                             |
 | Hosting         | Vercel (frontend), Render (indexer + database)                                            |
 
@@ -105,7 +105,7 @@ Yield distributes to LP shares
 
 - Node.js 20+
 - pnpm 9+
-- Go 1.22+
+- Go 1.25+
 - Docker
 - [Freighter](https://freighter.app) browser extension
 
@@ -148,6 +148,25 @@ Open [http://localhost:3000](http://localhost:3000), connect Freighter on testne
 
 ---
 
+## Build & Test
+
+Run these from the repository root after `pnpm install`. CI runs the same commands on every push and pull request against `main` (see [`.github/workflows/ci.yml`](./.github/workflows/ci.yml)).
+
+```bash
+# Build the SDK and the web app
+pnpm build
+
+# Run the SDK and web app unit test suites
+pnpm test
+
+# Run the Go indexer's test suite
+cd indexer && go test ./...
+```
+
+Building the web app reads `NEXT_PUBLIC_*` variables from `.env.local` (see step 2 above) — without it, `pnpm build` still succeeds but the app logs `Missing required environment variables` warnings.
+
+---
+
 ## Contributing
 
 We welcome contributions from the Stellar community. Before opening a PR, please read [CONTRIBUTING.md](./CONTRIBUTING.md).

apps/web/README.md

@@ -22,7 +22,7 @@ See the root [`README.md`](../../README.md) for the full project overview and de
 
 - Node.js 20+
 - pnpm 9+
-- Go 1.22+
+- Go 1.25+
 - PostgreSQL 15+ or Docker Compose
 - Freighter wallet configured for Stellar Testnet