Development Guide

Prerequisites

Postgres: docker exec pg18 psql -U postgres (postgres/postgres; databases vmall for dev, vmall_test for tests). Redis: container rdb8.
Rust stable + pnpm.

Run the stack

cargo run -p vmall-api            # API on :8080, migrations auto-apply on boot
pnpm --filter @vmall/mall dev     # storefront :3000
pnpm --filter @vmall/shop-admin dev
pnpm --filter @vmall/admin dev
pnpm dev                          # all frontends at once

Demo credentials (scripts/seed-demo.mjs, idempotent): admin@vmall.local / admin1234 (platform), shop@vmall.local / shop12345 (demo merchant), customer@vmall.local / customer123 (shopper).

Test

cargo test -p vmall-api           # integration tests against vmall_test + Redis

Rules: run the suite twice before archiving a change (the shared test DB is never truncated; a single green run can be luck). Use set -o pipefail when piping to grep, or FAILED lines get swallowed by grep's exit code.

Test DB migration drift (you edited an already-applied local migration): docker exec pg18 psql -U postgres -d vmall_test -c "DROP SCHEMA public CASCADE; CREATE SCHEMA public;" — migrations rebuild it on next run.

Build

pnpm --filter @vmall/<app> build  # per app; required for every app when
                                  # packages/shared changed

OpenSpec flow

New capability → openspec/changes/<name>/ with proposal + tasks + spec deltas; openspec validate <name> --strict must pass.
Implement; check tasks as you go.
Verify (tests ×2, builds, browser smoke), then openspec archive <name> --yes.
openspec validate --all --strict stays green.

The tigshop migration wave is tracked in openspec/MIGRATION-PLAN.md (temporary; deleted when all eight changes are archived).

Troubleshooting

Symptom	Fix
`Failed to resolve import "#app-manifest"`	`rm -rf apps/<app>/.nuxt`, restart dev
Page stuck on loading after dev restart	stale tab holds dead chunk hashes — fresh tab
curl to `127.0.0.1:3000` refused	dev binds IPv6; use `localhost`
cargo test green locally but list test flaky	shared DB; assert only on own fixtures

2.2 KiB Raw Blame History Unescape Escape