Cheatsheet

The everyday commands. Keep this page open. Deeper guides: Getting started, Testing, Deploy, Operations.

Install & build

npm install                 # install the whole workspace
npm run build               # tsc --build (shared → mcp-server)
npm run check               # full gate: format · lint · typecheck · test · knip · syncpack · type-coverage
npm run lint  / npm run format

Run the server locally

# stdio — no auth, no DB, in-memory store (fastest inner loop)
npm run dev:stdio -w @redline/mcp-server

# HTTP + full auth — Postgres + Keycloak + the MCP/REST server
cp .env.example .env
docker compose up --build postgres keycloak mcp-server
#   MCP:  http://localhost:3000/mcp      REST: http://localhost:3000/v1
#   Keycloak: http://localhost:8080      health: http://localhost:3000/healthz

# the webapp (Vite) — on :5173
npm run dev -w @redline/webapp
# both the HTTP server and the webapp together
npm run dev

Get a token & call the API

# password grant against the local Keycloak (test user: dealer / dealer)
TOKEN=$(curl -s http://localhost:8080/realms/redline/protocol/openid-connect/token \
  -d grant_type=password -d client_id=redline-mcp-client \
  -d username=dealer -d password=dealer \
  -d 'scope=openid listings:read listings:write' | jq -r .access_token)

# public read (no token)
curl -s 'http://localhost:3000/v1/listings?make=BMW&limit=5' | jq

# authenticated write
curl -s -X POST http://localhost:3000/v1/listings \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"type":"car","make":"BMW","model":"M3","year":2021,"priceCents":7500000,"currency":"EUR","mileageKm":12000,"fuelType":"petrol","transmission":"automatic","condition":"used"}' | jq

# end-to-end OAuth smoke test (health → metadata → token → tools → create → search)
node scripts/auth-smoke.mjs http://localhost:3000 http://auth.localhost:8080

Test & hardening suite

npm run stack:test:up        # hermetic Postgres + Keycloak + MCP on the redline_test DB
npm run seed:fixtures        # provision the known login users in Keycloak
npm run seed                 # large, deterministic dataset (flags: --listings --dealers --seed …)
npm run seed:reset           # truncate the test DB (guarded)

npm test                     # fast unit tests (DB-free)
npm run test:integration     # REST vs a real Postgres (testcontainers)
npm run test:e2e             # Playwright (real Keycloak login); :smoke / :ui / :report variants
npm run test:load            # Artillery (--profile smoke|average|stress|spike|soak|ci)
npm run test:security        # npm audit (prod High+) + app security tests

npm run stack:test:down      # tear the stack down

See Testing for the full phase reference, fixtures, and CI lanes.

Docs site (this site)

npm run docs:dev       # live preview on :5174 (also part of `npm run dev`)
npm run docs:build     # static build (fails on dead links)
npm run docs:preview   # preview the build

Deploy & ops (pointers)

git push origin main                       # CI builds images → deploys staging (app + docs)
git tag -a v0.3.1 -m "release: v0.3.1" && git push origin v0.3.1   # full release: staging + prod + /version + docs

VPS_HOST=<vps> npm run set-app-version -- 0.3.1    # stamp /version without a release
ssh -i ~/.ssh/redline deploy@<vps-host>            # see Operations
./deploy/deploy.sh staging                         # apply env / redeploy on the VPS

Full runbooks: Deploy · Operations (SSH, pgAdmin, email).