From 92ab66d737bc2afbf54cb31e4f54253ecab00779 Mon Sep 17 00:00:00 2001 From: Test User Date: Sun, 19 Apr 2026 12:38:19 +0000 Subject: [PATCH 1/2] ci: add frontend-only CI workflow --- .github/workflows/ci.yml | 302 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 302 insertions(+) create mode 100644 .github/workflows/ci.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..9b6153a --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,302 @@ +name: CI + +on: + push: + branches: [main, dev, uat] + pull_request: + branches: [main, dev, uat] + +concurrency: + group: ci-${{ github.ref }} + cancel-in-progress: true + +permissions: + contents: write + packages: write + security-events: write + +env: + REGISTRY: ghcr.io + IMAGE_NAME: cartsnitch/app + +jobs: + lint: + runs-on: runners-cartsnitch + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: "20" + cache: npm + - run: npm ci + - name: ESLint + run: npx eslint . + - name: Type check + run: npx tsc --noEmit + + test: + runs-on: runners-cartsnitch + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: "20" + cache: npm + - run: npm ci + - name: Run tests + run: npx vitest run + + audit: + runs-on: runners-cartsnitch + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: "20" + cache: npm + - run: npm ci + - name: Check for vulnerabilities + run: npm audit --audit-level=high + + e2e: + runs-on: runners-cartsnitch + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: "20" + cache: npm + - run: npm ci + - run: npx playwright install --with-deps chromium + - run: npx playwright test + + lighthouse: + runs-on: runners-cartsnitch + needs: [test] + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: "20" + cache: npm + - run: npm ci + - run: npm run build + - name: Install Chromium for Lighthouse + run: | + npm install -g playwright + npx playwright install --with-deps chromium + - name: Start preview server + run: | + npm run preview & + npx wait-on http://localhost:4173/ --timeout 30000 + - name: Run Lighthouse CI + run: | + CHROME_PATH=$(find /home/runner/.cache/ms-playwright -name chrome -type f 2>/dev/null | head -1) + npm install -g @lhci/cli + CHROME_PATH="$CHROME_PATH" lhci autorun --chrome-flags="--headless=new --no-sandbox --disable-gpu --disable-dev-shm-usage" + + build-and-push: + runs-on: runners-cartsnitch + if: github.event_name == 'push' + needs: [lint, test, e2e] + outputs: + calver_tag: ${{ steps.calver.outputs.version }} + sha_tag: sha-${{ github.sha }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Generate CalVer tag + id: calver + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + run: | + DATE_TAG=$(date -u +%Y.%m.%d) + EXISTING=$(git tag -l "v${DATE_TAG}*" | sort -V | tail -1) + if [ -z "$EXISTING" ]; then + VERSION="$DATE_TAG" + elif [ "$EXISTING" = "v${DATE_TAG}" ]; then + VERSION="${DATE_TAG}.2" + else + BUILD_NUM=$(echo "$EXISTING" | sed "s/v${DATE_TAG}\.//") + VERSION="${DATE_TAG}.$((BUILD_NUM + 1))" + fi + echo "version=$VERSION" >> "$GITHUB_OUTPUT" + echo "CalVer tag: $VERSION" + + - name: Log in to Docker Hub + if: github.event_name == 'push' + uses: docker/login-action@v3 + with: + username: ${{ secrets.DOCKERHUB_USERNAME }} + password: ${{ secrets.DOCKERHUB_TOKEN }} + + - name: Log in to GHCR + if: github.event_name == 'push' + uses: docker/login-action@v3 + with: + registry: ${{ env.REGISTRY }} + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + - name: Extract metadata + id: meta + uses: docker/metadata-action@v5 + with: + images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} + tags: | + type=sha,prefix=sha-,format=long + type=raw,value=${{ steps.calver.outputs.version }},enable=${{ github.ref == 'refs/heads/main' }} + type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }} + + - name: Build Docker image + uses: docker/build-push-action@v6 + with: + context: . + load: true + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} + target: prod + cache-from: type=gha + cache-to: type=gha,mode=max + + - name: Scan frontend image for vulnerabilities + uses: anchore/scan-action@v5 + id: scan + env: + GRYPE_CONFIG: .grype.yaml + with: + image: "${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:sha-${{ github.sha }}" + fail-build: true + severity-cutoff: high + only-fixed: "true" + output-format: sarif + + - name: Upload frontend scan results to GitHub Security + uses: github/codeql-action/upload-sarif@v3 + if: always() + with: + sarif_file: ${{ steps.scan.outputs.sarif }} + + - name: Push Docker image + if: github.event_name == 'push' + uses: docker/build-push-action@v6 + with: + context: . + push: true + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} + target: prod + cache-from: type=gha + + - name: Create git tag + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + run: | + git tag "v${{ steps.calver.outputs.version }}" + git push origin "v${{ steps.calver.outputs.version }}" + + deploy-dev: + runs-on: runners-cartsnitch + needs: [build-and-push] + if: always() && !cancelled() && github.event_name == 'push' && (github.ref == 'refs/heads/dev' || github.ref == 'refs/heads/main') + steps: + - name: Generate GitHub App token + id: app-token + uses: actions/create-github-app-token@v1 + with: + app-id: ${{ secrets.CARTSNITCH_APP_ID }} + private-key: ${{ secrets.CARTSNITCH_APP_PRIVATE_KEY }} + owner: ${{ github.repository_owner }} + repositories: infra + + - name: Checkout infra repo + uses: actions/checkout@v4 + with: + repository: cartsnitch/infra + token: ${{ steps.app-token.outputs.token }} + ref: main + path: infra + + - name: Install kubectl + uses: azure/setup-kubectl@v4 + + - name: Install kustomize + uses: imranismail/setup-kustomize@v2 + + - name: Determine image tag for frontend + id: frontend_tag + run: | + if [ "${{ github.ref }}" == "refs/heads/main" ]; then + echo "tag=${{ needs.build-and-push.outputs.calver_tag }}" >> "$GITHUB_OUTPUT" + else + echo "tag=${{ needs.build-and-push.outputs.sha_tag }}" >> "$GITHUB_OUTPUT" + fi + + - name: Update frontend image tag + if: needs.build-and-push.result == 'success' + run: | + cd infra/apps/overlays/dev + kustomize edit set image ghcr.io/cartsnitch/app:${{ steps.frontend_tag.outputs.tag }} + + - name: Commit and push to infra + run: | + cd infra + git config user.name "cartsnitch-ci[bot]" + git config user.email "cartsnitch-ci[bot]@users.noreply.github.com" + git add apps/overlays/dev/kustomization.yaml + git commit -m "ci(dev): update cartsnitch/app image" + git pull --rebase origin main + git push origin main + + deploy-uat: + runs-on: runners-cartsnitch + needs: [build-and-push] + if: always() && !cancelled() && github.event_name == 'push' && (github.ref == 'refs/heads/uat' || github.ref == 'refs/heads/main') + steps: + - name: Generate GitHub App token + id: app-token + uses: actions/create-github-app-token@v1 + with: + app-id: ${{ secrets.CARTSNITCH_APP_ID }} + private-key: ${{ secrets.CARTSNITCH_APP_PRIVATE_KEY }} + owner: ${{ github.repository_owner }} + repositories: infra + + - name: Checkout infra repo + uses: actions/checkout@v4 + with: + repository: cartsnitch/infra + token: ${{ steps.app-token.outputs.token }} + ref: main + path: infra + + - name: Install kubectl + uses: azure/setup-kubectl@v4 + + - name: Install kustomize + uses: imranismail/setup-kustomize@v2 + + - name: Determine image tag for frontend + id: frontend_tag + run: | + if [ "${{ github.ref }}" == "refs/heads/main" ]; then + echo "tag=${{ needs.build-and-push.outputs.calver_tag }}" >> "$GITHUB_OUTPUT" + else + echo "tag=${{ needs.build-and-push.outputs.sha_tag }}" >> "$GITHUB_OUTPUT" + fi + + - name: Update frontend image tag + if: needs.build-and-push.result == 'success' + run: | + cd infra/apps/overlays/uat + kustomize edit set image ghcr.io/cartsnitch/app:${{ steps.frontend_tag.outputs.tag }} + + - name: Commit and push to infra + run: | + cd infra + git config user.name "cartsnitch-ci[bot]" + git config user.email "cartsnitch-ci[bot]@users.noreply.github.com" + git add apps/overlays/uat/kustomization.yaml + git commit -m "ci(uat): update cartsnitch/app image" + git pull --rebase origin main + git push origin main \ No newline at end of file -- 2.52.0 From 7ae6382f8bb79d3dca429f2f55610279128a1084 Mon Sep 17 00:00:00 2001 From: Test User Date: Sun, 19 Apr 2026 12:39:12 +0000 Subject: [PATCH 2/2] docs: update CLAUDE.md for standalone frontend repo --- CLAUDE.md | 58 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 37 insertions(+), 21 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 8f6fc1a..cc396a1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,26 +1,21 @@ -# CartSnitch Monorepo +# CartSnitch Frontend ## Project Context -CartSnitch is a self-hosted grocery price intelligence platform. This repo (`cartsnitch/cartsnitch`) is the **monorepo** containing the flagship frontend PWA and core backend services. +CartSnitch is a self-hosted grocery price intelligence platform. This repo (`cartsnitch/app`) is the **standalone frontend PWA** — a mobile-first React application. **GitHub org:** github.com/cartsnitch **Domain:** cartsnitch.com -### Monorepo Layout - -| Directory | Service | Purpose | -|-----------|---------|---------| -| `/` (root) | Frontend | React PWA, mobile-first (this directory) | -| `auth/` | Auth | Better-Auth Node.js service (session management, email/password, OAuth) | -| `api/` | API Gateway | Frontend-facing REST API | -| `common/` | Common | Shared Python models, schemas, Alembic migrations | -| `receiptwitness/` | ReceiptWitness | Purchase data ingestion via retailer scrapers | - -### Other CartSnitch Repos (still separate) +### CartSnitch Repos | Repo | Service | Purpose | |------|---------|---------| +| `cartsnitch/app` | Frontend | React PWA, mobile-first (this repo) | +| `cartsnitch/auth` | Auth | Better-Auth Node.js service (session management, email/password, OAuth) | +| `cartsnitch/api` | API Gateway | Frontend-facing REST API | +| `cartsnitch/common` | Common | Shared Python models, schemas, Alembic migrations | +| `cartsnitch/receiptwitness` | ReceiptWitness | Purchase data ingestion via retailer scrapers | | `cartsnitch/stickershock` | StickerShock | Price increase detection & CPI comparison | | `cartsnitch/shrinkray` | ShrinkRay | Shrinkflation monitoring | | `cartsnitch/clipartist` | ClipArtist | Coupon/deal watching & shopping optimization | @@ -41,20 +36,19 @@ The frontend is a mobile-first PWA that serves as the primary user interface for ## Tech Stack -- React 18+ (or Next.js if SSR/SSG is valuable for public pages) +- React 18+ - TypeScript - Tailwind CSS (mobile-first responsive design) - Workbox (service worker, offline caching, PWA manifest) -- Recharts or Chart.js (price trend visualizations) +- Recharts (price trend visualizations) - TanStack Query (React Query) for data fetching and caching - React Router (client-side routing) -- Zustand or Jotai (lightweight state management) +- Zustand (state management) - Vite (build tool) ## Repo Structure ``` -frontend/ ├── CLAUDE.md ├── README.md ├── package.json @@ -63,6 +57,9 @@ frontend/ ├── tailwind.config.ts ├── Dockerfile # Multi-stage: build + nginx serve ├── docker-compose.yml # Local dev +├── .github/ +│ └── workflows/ +│ └── ci.yml # CI: lint, test, audit, e2e, lighthouse, build-and-push, deploy ├── public/ │ ├── manifest.json # PWA manifest │ ├── sw.js # Service worker (Workbox generated) @@ -131,7 +128,7 @@ frontend/ │ │ ├── EmptyState.tsx │ │ ├── StoreLogo.tsx │ │ └── ErrorBoundary.tsx -│ ├── stores/ # Zustand/Jotai state stores +│ ├── stores/ # Zustand state stores │ │ ├── authStore.ts │ │ └── uiStore.ts │ ├── utils/ @@ -144,6 +141,10 @@ frontend/ │ ├── price.ts │ ├── coupon.ts │ └── alert.ts +├── e2e/ +│ └── ... +├── scripts/ +│ └── ... └── tests/ └── ... ``` @@ -167,7 +168,7 @@ frontend/ All data comes from the CartSnitch API gateway (`cartsnitch/api`). Base URL configured via environment variable `VITE_API_URL`. -- **Authentication via Better-Auth** (`auth/` service). Sessions are managed via httpOnly cookies — no tokens in localStorage or memory. +- **Authentication via Better-Auth** (`cartsnitch/auth` service). Sessions are managed via httpOnly cookies — no tokens in localStorage or memory. - Auth service URL configured via `VITE_AUTH_URL` (default: `http://localhost:3001`) - Frontend uses `better-auth/react` client for sign-in, sign-up, sign-out, and `useSession()` hook - API gateway validates sessions by querying the shared `sessions` table in Postgres @@ -184,9 +185,24 @@ All data comes from the CartSnitch API gateway (`cartsnitch/api`). Base URL conf - `npm run build` for production build - Lint with ESLint, format with Prettier +## CI/CD + +This repo uses a GitHub Actions CI pipeline (`.github/workflows/ci.yml`): + +- **lint** — ESLint + TypeScript check +- **test** — Vitest +- **audit** — npm audit +- **e2e** — Playwright +- **lighthouse** — Lighthouse CI +- **build-and-push** — builds Docker image, Grype vulnerability scan, pushes to `ghcr.io/cartsnitch/app` +- **deploy-dev** — updates `ghcr.io/cartsnitch/app` image tag in `infra/apps/overlays/dev/kustomization.yaml` +- **deploy-uat** — updates `ghcr.io/cartsnitch/app` image tag in `infra/apps/overlays/uat/kustomization.yaml` + +Image tags: CalVer (`YYYY.MM.DD[.N]`) on `main`, `sha-` on `dev`/`uat`. + ## Important Notes - The store account connection flow is the most complex UX. Users need to authenticate with each retailer. This likely involves opening a controlled browser window/iframe where they log in, and CartSnitch captures the resulting session. Design this flow carefully — it needs to feel safe and trustworthy. -- Public price transparency pages should be SSR-friendly or statically generated for SEO if the "naming and shaming" feature is going to get organic traffic. Consider Next.js for these pages specifically, or a separate lightweight static site. +- Public price transparency pages should be SSR-friendly or statically generated for SEO if the "naming and shaming" feature is going to get organic traffic. - The optimized shopping list is the killer feature for retention. Make it dead simple: add items → see the split → go shop. No friction. -- Push notifications (via service worker) for price alerts and deal notifications are a Phase 2+ feature but design the alert system with this in mind. +- Push notifications (via service worker) for price alerts and deal notifications are a Phase 2+ feature but design the alert system with this in mind. \ No newline at end of file -- 2.52.0