collective-lists/Justfile

# Colectivo — task runner
# Requires: just, docker, pnpm

set dotenv-load := true

# Alias: docker compose with correct project root so .env is always found
dc_dev := "docker compose --env-file .env -f infra/docker-compose.dev.yml"
dc_prod := "docker compose --env-file .env -f infra/docker-compose.prod.yml"

# ── Setup ─────────────────────────────────────────────────────────────────────

# First-time (and idempotent) local environment setup
setup:
    bash setup.sh

# ── Dev ───────────────────────────────────────────────────────────────────────

# Start full local stack (Docker services + SvelteKit dev server)
dev:
    {{dc_dev}} up -d
    pnpm --filter @colectivo/web dev

# Stop all services (Docker stack + SvelteKit dev server)
stop:
    {{dc_dev}} down
    -pkill -f "vite" 2>/dev/null || true

# Stop local Docker stack
dev-stop:
    {{dc_dev}} down

# Stop and remove all volumes (full reset)
dev-clean:
    {{dc_dev}} down -v

# ── Database ──────────────────────────────────────────────────────────────────

# Drop, migrate, and seed the dev database
db-reset:
    supabase db reset

# Apply pending migrations
db-migrate:
    supabase db push

# Apply dev seed data
db-seed:
    docker exec -i colectivo-dev-db-1 psql -U postgres < supabase/seed.sql

# Regenerate TypeScript types from Supabase schema.
# Writes to a tempfile first so a missing/failing `supabase` CLI does not
# truncate the existing hand-curated database.ts (which would silently
# break every TS consumer in the monorepo).
db-types:
    #!/usr/bin/env bash
    set -euo pipefail
    if ! command -v supabase >/dev/null 2>&1; then
        echo "supabase CLI not installed — database.ts is hand-curated, edit it manually" >&2
        exit 1
    fi
    tmp=$(mktemp)
    supabase gen types typescript --local > "$tmp"
    mv "$tmp" packages/types/src/database.ts
    echo "Types written to packages/types/src/database.ts"

# Open Supabase Studio
db-open:
    open http://localhost:54323

# ── Keycloak ──────────────────────────────────────────────────────────────────

# Export Keycloak realm to keycloak/realm-export.json
kc-export:
    {{dc_dev}} exec keycloak \
        /opt/keycloak/bin/kc.sh export \
        --realm colectivo \
        --users realm_file \
        --file /tmp/realm-export.json
    {{dc_dev}} cp keycloak:/tmp/realm-export.json keycloak/realm-export.json
    echo "Exported to keycloak/realm-export.json"

# Open Keycloak Admin Console
kc-open:
    open http://localhost:8080/admin

# ── Build ─────────────────────────────────────────────────────────────────────

# Build all packages
build:
    pnpm turbo run build

# Run the production build locally against the dev Docker stack (port 3000)
serve: build
    {{dc_dev}} up -d
    PORT=3000 node apps/web/build/index.js

# Type-check all packages (also lints CHANGELOG.md — Fase 17.4.3)
check:
    node scripts/check-changelog.mjs
    pnpm turbo run check

# Lint all packages
lint:
    pnpm turbo run lint

# Run tests
test:
    pnpm turbo run test

# ── Testing ───────────────────────────────────────────────────────────────────

# Run every test suite (pgTAP + Vitest integration + apps/web unit + Playwright E2E).
# Requires `just dev` to already be running — the stack must be healthy.
test-all: test-db test-integration test-unit test-e2e

# Run apps/web Vitest unit tests (browser-env + jsdom + fake-indexeddb).
# Currently covers the offline sync queue (Fase 2b.2).
test-unit:
    pnpm --filter @colectivo/web test:unit

# Run pgTAP SQL tests directly against the dev database
# `set dotenv-load` at the top of this file sources .env so POSTGRES_PASSWORD
# is available — we forward it to psql via PGPASSWORD.
test-db:
    #!/usr/bin/env bash
    set -euo pipefail
    for f in supabase/tests/*.sql; do
        PGPASSWORD="$POSTGRES_PASSWORD" psql -U postgres -h localhost -d postgres \
            -v ON_ERROR_STOP=1 -f "$f"
    done

# Run Vitest integration tests (RLS + trigger assertions via supabase-js)
test-integration:
    pnpm --filter @colectivo/test-utils test

# Install Playwright browsers (chromium + webkit). WebKit is required for
# touch-gesture specs (Fase 9.4 swipe-toggle) — the *.webkit.test.ts files
# are gated to that project in playwright.config.ts.
playwright-install:
    pnpm --filter @colectivo/web exec playwright install chromium webkit

# Run Playwright E2E tests (headless). Includes the WebKit project — make
# sure `just playwright-install` has run at least once.
test-e2e:
    pnpm --filter @colectivo/web exec playwright test

# Run Playwright E2E tests in headed mode (for debugging)
test-e2e-headed:
    pnpm --filter @colectivo/web exec playwright test --headed

# Run only the WebKit (Mobile Safari) touch-gesture specs (Fase 9.4).
# Gated behind RUN_WEBKIT=1 in playwright.config so it stays out of the
# default test-all (WebKit needs system libs not available on every host
# — see `just playwright-install` and `sudo pnpm exec playwright install-deps`).
test-webkit:
    RUN_WEBKIT=1 pnpm --filter @colectivo/web exec playwright test --project=webkit

# Run Kong rate-limit verification tests. Restarts Kong first to ensure a
# clean counter state (tests burn through the minute + hour quotas). Not
# part of test-all because the tests share the rate-limit counter with the
# rest of the integration suite.
test-rate-limit:
    #!/usr/bin/env bash
    set -euo pipefail
    {{dc_dev}} up -d --force-recreate kong
    sleep 3
    export RUN_RATE_LIMIT_TESTS=1
    pnpm --filter @colectivo/test-utils test -- rate-limit

# Build a prod bundle, serve it on :3000, run Lighthouse against PWA /
# Accessibility / Best-Practices. Fails if any score drops below 90.
# Must run while `just dev` (docker stack) is up — Lighthouse loads the
# real app which hits Supabase via Kong.
lighthouse:
    #!/usr/bin/env bash
    set -euo pipefail
    pnpm --filter @colectivo/web build
    PORT=3000 node apps/web/build/index.js &
    SERVER_PID=$!
    trap "kill $SERVER_PID 2>/dev/null || true" EXIT
    for i in 1 2 3 4 5 6 7 8 9 10; do
        if curl -sf http://localhost:3000/ -o /dev/null; then break; fi
        sleep 1
    done
    pnpm --filter @colectivo/web exec lighthouse http://localhost:3000 \
        --only-categories=pwa,accessibility,best-practices \
        --output=html --output-path=./lighthouse-report.html \
        --chrome-flags='--headless --no-sandbox' \
        --quiet

# Run the RLS isolation curl audit — complements rls-audit.test.ts.
rls-audit:
    infra/scripts/rls-audit.sh

# ── Backup & Restore ──────────────────────────────────────────────────────────

# Take a manual backup of a service (e.g. just backup supabase)
backup service:
    infra/scripts/backup.sh {{service}}

# Restore a backup file (e.g. just restore supabase backups/2024-01-01.dump)
restore service file:
    infra/scripts/restore.sh {{service}} {{file}}

# ── Production ────────────────────────────────────────────────────────────────

# Deploy to production via SSH (ambrosio / erosi.limonia.net).
# Pre-deploy: dumps the prod DB to /opt/colectivo/backups/predeploy-<ts>-<sha>.sql.gz
# Post-deploy: appends (timestamp, sha, backup) to /opt/colectivo/.deploys.log
deploy:
    infra/scripts/deploy-erosi.sh

# List recent prod deploys (timestamp / sha / backup-file).
rollback-list:
    infra/scripts/rollback-erosi.sh --list

# Roll back code AND database to the previous deploy.
# For a specific deploy: `just rollback-to <sha>`.
rollback:
    infra/scripts/rollback-erosi.sh --previous

# Roll back to a specific deploy by sha (must exist in .deploys.log on prod).
rollback-to sha:
    infra/scripts/rollback-erosi.sh --to={{sha}}

# Roll back only code (skip DB restore). Useful if the regression is UI-only.
rollback-code:
    infra/scripts/rollback-erosi.sh --previous --code-only

# Stream production Docker logs
logs:
    {{dc_prod}} logs -f